From aba516de366c4d7fb8c8c21448628407bbc3e713 Mon Sep 17 00:00:00 2001
From: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 18 May 2024 06:10:52 +0000
Subject: [PATCH] Deployed 2ae3ef76 to v3 with MkDocs 1.6.0 and mike 2.1.1

---
 v3/CHANGELOG-v3/index.html           |  29 ++++++++++++++++++++++-----
 v3/__pycache__/hooks.cpython-311.pyc | Bin 8282 -> 8282 bytes
 v3/search/search_index.json          |   2 +-
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/v3/CHANGELOG-v3/index.html b/v3/CHANGELOG-v3/index.html
index 9ca3702255..dd4fa34e06 100644
--- a/v3/CHANGELOG-v3/index.html
+++ b/v3/CHANGELOG-v3/index.html
@@ -1557,6 +1557,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#v300-b0198-pre-release" class="md-nav__link">
+    <span class="md-ellipsis">
+      v3.0.0-B0198 (pre-release)
+    </span>
+  </a>
+  
 </li>
       
         <li class="md-nav__item">
@@ -2617,6 +2626,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#v300-b0198-pre-release" class="md-nav__link">
+    <span class="md-ellipsis">
+      v3.0.0-B0198 (pre-release)
+    </span>
+  </a>
+  
 </li>
       
         <li class="md-nav__item">
@@ -2730,6 +2748,7 @@ <h1 id="change-log">Change log<a class="headerlink" href="#change-log" title="Pe
 </li>
 </ul>
 <h2 id="unreleased">Unreleased<a class="headerlink" href="#unreleased" title="Permanent link">#</a></h2>
+<h2 id="v300-b0198-pre-release">v3.0.0-B0198 (pre-release)<a class="headerlink" href="#v300-b0198-pre-release" title="Permanent link">#</a></h2>
 <p>What's changed since pre-release v3.0.0-B0153:</p>
 <ul>
 <li>Engineering:<ul>
@@ -2964,7 +2983,7 @@ <h2 id="v300-b0084-pre-release">v3.0.0-B0084 (pre-release)<a class="headerlink"
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">May 17, 2024</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">May 18, 2024</span>
   </span>
 
     
@@ -2992,14 +3011,14 @@ <h2 id="v300-b0084-pre-release">v3.0.0-B0084 (pre-release)<a class="headerlink"
     
     <nav>
       
-        <a href="https://github.com/apps/dependabot" class="md-author" title="@dependabot[bot]">
+        <a href="https://github.com/BernieWhite" class="md-author" title="@BernieWhite">
           
-          <img src="https://avatars.githubusercontent.com/in/29110?v=4&size=72" alt="dependabot[bot]">
+          <img src="https://avatars.githubusercontent.com/u/13513058?v=4&size=72" alt="BernieWhite">
         </a>
       
-        <a href="https://github.com/BernieWhite" class="md-author" title="@BernieWhite">
+        <a href="https://github.com/apps/dependabot" class="md-author" title="@dependabot[bot]">
           
-          <img src="https://avatars.githubusercontent.com/u/13513058?v=4&size=72" alt="BernieWhite">
+          <img src="https://avatars.githubusercontent.com/in/29110?v=4&size=72" alt="dependabot[bot]">
         </a>
       
       
diff --git a/v3/__pycache__/hooks.cpython-311.pyc b/v3/__pycache__/hooks.cpython-311.pyc
index d12ccaf61b91a1e482c48a82f73f571a00f6cab7..b35fc900fc177d3d9bf3f244bf2cf55b3526dad3 100644
GIT binary patch
delta 19
ZcmccRaLa*fIWI340}%MSZR842002331jqmY

delta 19
ZcmccRaLa*fIWI340}v=!ZR842001~D1djj!

diff --git a/v3/search/search_index.json b/v3/search/search_index.json
index 4d5b118ed2..5bf8e67c63 100644
--- a/v3/search/search_index.json
+++ b/v3/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"CHANGELOG-v0/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Attention</p> <p>PSRule v0 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.</p>"},{"location":"CHANGELOG-v0/#v0220","title":"v0.22.0","text":"<p>What's changed since v0.21.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>HasFields</code> assertion helper to check all fields exist. #578</li> <li>Updated <code>HasField</code> to check if any of the specified fields exist. #578</li> </ul> </li> <li>General improvements:<ul> <li>Input format detection now includes <code>.jsonc</code> and <code>.markdown</code> file extensions. #575</li> <li>Improved support for cross module rule dependencies. #248<ul> <li>Rule dependencies are now automatically imported.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling for null or empty arrays with <code>StartsWith</code>, <code>Contains</code>, <code>EndsWith</code>, <code>In</code>, and <code>NotIn</code>. #579</li> </ul> </li> </ul> <p>What's changed since pre-release v0.22.0-B2010014:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0220-b2010014-pre-release","title":"v0.22.0-B2010014 (pre-release)","text":"<p>What's changed since v0.21.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>HasFields</code> assertion helper to check all fields exist. #578</li> <li>Updated <code>HasField</code> to check if any of the specified fields exist. #578</li> </ul> </li> <li>General improvements:<ul> <li>Input format detection now includes <code>.jsonc</code> and <code>.markdown</code> file extensions. #575</li> <li>Improved support for cross module rule dependencies. #248<ul> <li>Rule dependencies are now automatically imported.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling for null or empty arrays with <code>StartsWith</code>, <code>Contains</code>, <code>EndsWith</code>, <code>In</code>, and <code>NotIn</code>. #579</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210","title":"v0.21.0","text":"<p>What's changed since v0.20.0:</p> <ul> <li>Engine features:<ul> <li>Added support for formatting results as markdown. #474<ul> <li>Use <code>-OutputFormat Markdown</code> or configure <code>Output.Format</code> to output markdown.</li> <li>To format as either detail or summary, use the <code>-As</code> parameter or configure <code>Output.As</code>.</li> </ul> </li> <li>Added character case assertion helpers <code>IsLower</code>, and <code>IsUpper</code>. #555<ul> <li><code>IsLower</code> checks that all letters in a field value are lowercase.</li> <li><code>IsUpper</code> checks that all letters in a field value are uppercase.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Numerical strings can be converted with numeric assertion helpers. #550</li> <li>Added outcome <code>Output.Outcome</code> as a configurable option. #552</li> <li>Added help links and default snippets to schemas. #561</li> <li>Improved rule error reporting by including rule and source location. #565</li> </ul> </li> <li>Engineering:<ul> <li>Bump Manatee.Json from 13.0.2 to 13.0.3. #563</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed NUnit report reasons should be escaped in markdown. #471</li> <li>Fixed reporting of error when rule error is handled. #564<ul> <li>Additionally rules can use <code>-ErrorAction Ignore</code> to ignore non-exception errors.</li> </ul> </li> <li>Fixed first exception stops other rules from being processed. #566</li> </ul> </li> </ul> <p>What's changed since pre-release v0.21.0-B2010010:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2010010-pre-release","title":"v0.21.0-B2010010 (pre-release)","text":"<p>What's changed since pre-release v0.21.0-B2010003:</p> <ul> <li>General improvements:<ul> <li>Improved rule error reporting by including rule and source location. #565</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2010003-pre-release","title":"v0.21.0-B2010003 (pre-release)","text":"<p>What's changed since pre-release v0.21.0-B2009016:</p> <ul> <li>General improvements:<ul> <li>Added help links and default snippets to schemas. #561</li> </ul> </li> <li>Engineering:<ul> <li>Bump Manatee.Json from 13.0.2 to 13.0.3. #563</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed reporting of error when rule error is handled. #564<ul> <li>Additionally rules can use <code>-ErrorAction Ignore</code> to ignore non-exception errors.</li> </ul> </li> <li>Fixed first exception stops other rules from being processed. #566</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2009016-pre-release","title":"v0.21.0-B2009016 (pre-release)","text":"<p>What's changed since pre-release v0.21.0-B2009006:</p> <ul> <li>Engine features:<ul> <li>Added character case assertion helpers <code>IsLower</code>, and <code>IsUpper</code>. #555<ul> <li><code>IsLower</code> checks that all letters in a field value are lowercase.</li> <li><code>IsUpper</code> checks that all letters in a field value are uppercase.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed NUnit report reasons should be escaped in markdown. #471</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2009006-pre-release","title":"v0.21.0-B2009006 (pre-release)","text":"<p>What's changed since v0.20.0:</p> <ul> <li>Engine features:<ul> <li>Added support for formatting results as markdown. #474<ul> <li>Use <code>-OutputFormat Markdown</code> or configure <code>Output.Format</code> to output markdown.</li> <li>To format as either detail or summary, use the <code>-As</code> parameter or configure <code>Output.As</code>.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Numerical strings can be converted with numeric assertion helpers. #550</li> <li>Added outcome <code>Output.Outcome</code> as a configurable option. #552</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200","title":"v0.20.0","text":"<p>What's changed since v0.19.0:</p> <ul> <li>Engine features:<ul> <li>Added support for scanning repository files. #524<ul> <li>Added <code>File</code> input type (<code>-InputType File</code>) to scan for files without deserializing them.</li> <li>Added <code>Input.PathIgnore</code> option to ignore files.</li> <li>When using the <code>File</code> input type path specs in <code>.gitignore</code> are ignored.</li> </ul> </li> <li>Added <code>Get-PSRuleTarget</code> cmdlet to read input files and return raw objects. #525<ul> <li>This cmdlet can be used to troubleshoot PSRule input issues.</li> </ul> </li> <li>Baselines can now be flagged as obsolete. #499<ul> <li>Set the <code>metadata.annotations.obsolete</code> property to <code>true</code> to flag a baseline as obsolete.</li> <li>When an obsolete baseline is used, a warning will be generated.</li> </ul> </li> <li>Added file assertion helpers <code>FileHeader</code>, and <code>FilePath</code>. #534<ul> <li><code>FileHeader</code> checks for a comment header in the file.</li> <li><code>FilePath</code> checks that a file path (optionally with suffixes) exist.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added automatic binding for Rule object. #542</li> </ul> </li> <li>Engineering:<ul> <li>Warn when deprecated <code>$Rule</code> properties are used. #536 #545<ul> <li>First usage of deprecated property generates a warning.</li> <li>Rule using deprecated property is flagged in debug output.</li> </ul> </li> <li>Bump YamlDotNet dependency to v8.1.2. #439</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed out of bounds exception when empty markdown documentation is used. #516</li> </ul> </li> </ul> <p>What's changed since pre-release v0.20.0-B2009013:</p> <ul> <li>Bug fixes:<ul> <li>Fixed excessive obsolete property warnings. #545</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2009013-pre-release","title":"v0.20.0-B2009013 (pre-release)","text":"<p>What's changed since pre-release v0.20.0-B2009007:</p> <ul> <li>General improvements:<ul> <li>Added automatic binding for Rule object. #542</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>InputFileInfo</code> <code>Type</code> property causes downstream binding issues. #541</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2009007-pre-release","title":"v0.20.0-B2009007 (pre-release)","text":"<p>What's changed since pre-release v0.20.0-B2008010:</p> <ul> <li>Engine features:<ul> <li>Added file assertion helpers <code>FileHeader</code>, and <code>FilePath</code>. #534<ul> <li><code>FileHeader</code> checks for a comment header in the file.</li> <li><code>FilePath</code> checks that a file path (optionally with suffixes) exist.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Warn when deprecated <code>$Rule</code> properties are used. #536</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed out of bounds exception when empty markdown documentation is used. #516</li> <li>Fixed lines breaks in <code>RepositoryInfo</code> target name with git ref. #538</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2008010-pre-release","title":"v0.20.0-B2008010 (pre-release)","text":"<p>What's changed since pre-release v0.20.0-B2008002:</p> <ul> <li>Engine features:<ul> <li>Baselines can now be flagged as obsolete. #499<ul> <li>Set the <code>metadata.annotations.obsolete</code> property to <code>true</code> to flag a baseline as obsolete.</li> <li>When an obsolete baseline is used, a warning will be generated.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to v8.1.2. #439</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2008002-pre-release","title":"v0.20.0-B2008002 (pre-release)","text":"<p>What's changed since v0.19.0:</p> <ul> <li>Engine features:<ul> <li>Added support for scanning repository files. #524<ul> <li>Added <code>File</code> input type (<code>-InputType File</code>) to scan for files without deserializing them.</li> <li>Added <code>Input.PathIgnore</code> option to ignore files.</li> <li>When using the <code>File</code> input type path specs in <code>.gitignore</code> are ignored.</li> </ul> </li> <li>Added <code>Get-PSRuleTarget</code> cmdlet to read input files and return raw objects. #525<ul> <li>This cmdlet can be used to troubleshoot PSRule input issues.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190","title":"v0.19.0","text":"<p>What's changed since v0.18.1:</p> <ul> <li>Engine features:<ul> <li>Added <code>Reason</code> method to assertion results. #500<ul> <li>This new method, streamlines setting custom reasons particularly with formatted strings.</li> <li>The <code>Reason</code> method replaces any previously set reasons with a custom string.</li> <li>Optional arguments can be provided to be included in string formatting.</li> </ul> </li> <li>Improvements to assertion methods.<ul> <li>Added regular expression assertion helpers <code>Match</code>, and <code>NotMatch</code>. #502</li> <li>Added collection assertion helpers <code>In</code>, and <code>NotIn</code>. #501</li> </ul> </li> <li>Added module version constraints. #498<ul> <li>The module versions that PSRule uses can be constrained.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed styling for no rule files warning with <code>Assert-PSRule</code>. #484</li> <li>Fixed actual value in reason for numeric comparison assertion method. #505</li> </ul> </li> </ul> <p>What's changed since pre-release v0.19.0-B2007030:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2007030-pre-release","title":"v0.19.0-B2007030 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed <code>Assert.In</code> unable to compare PSObject wrapped array items. #512</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2007023-pre-release","title":"v0.19.0-B2007023 (pre-release)","text":"<ul> <li>Engine features:<ul> <li>Added <code>Reason</code> method to assertion results. #500<ul> <li>This new method, streamlines setting custom reasons particularly with formatted strings.</li> <li>The <code>Reason</code> method replaces any previously set reasons with a custom string.</li> <li>Optional arguments can be provided to be included in string formatting.</li> </ul> </li> <li>Improvements to assertion methods.<ul> <li>Added regular expression assertion helpers <code>Match</code>, and <code>NotMatch</code>. #502</li> <li>Added collection assertion helpers <code>In</code>, and <code>NotIn</code>. #501</li> </ul> </li> <li>Added module version constraints. #498<ul> <li>The module versions that PSRule uses can be constrained.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed styling for no rule files warning with <code>Assert-PSRule</code>. #484</li> <li>Fixed actual value in reason for numeric comparison assertion method. #505</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0181","title":"v0.18.1","text":"<p>What's changed since v0.18.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed unable to read properties for .NET <code>DynamicObject</code>. #491</li> <li>Fixed read of JSON input format with null array item. #490</li> <li>Fixed <code>Csv</code> output format with summary for <code>Invoke-PSRule</code>. #486</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2006027-pre-release","title":"v0.19.0-B2006027 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed unable to read properties for .NET <code>DynamicObject</code>. #491</li> <li>Fixed read of JSON input format with null array item. #490</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2006018-pre-release","title":"v0.19.0-B2006018 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed <code>Csv</code> output format with summary for <code>Invoke-PSRule</code>. #486</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0180","title":"v0.18.0","text":"<p>What's changed since v0.17.0:</p> <ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting. #472<ul> <li>Added recommendation and reasons for <code>AzurePipelines</code> and <code>GitHubActions</code> styles.</li> <li>Summary line is has been updated to include synopsis instead of reasons.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed binding with <code>ModuleConfig</code>. #468</li> <li>Fixed recommendation output with client style. #467</li> </ul> </li> </ul> <p>What's changed since pre-release v0.18.0-B2005015:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0180-b2005015-pre-release","title":"v0.18.0-B2005015 (pre-release)","text":"<ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting. #472<ul> <li>Added recommendation and reasons for <code>AzurePipelines</code> and <code>GitHubActions</code> styles.</li> <li>Summary line is has been updated to include synopsis instead of reasons.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed binding with <code>ModuleConfig</code>. #468</li> <li>Fixed recommendation output with client style. #467</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0170","title":"v0.17.0","text":"<p>What's changed since v0.16.0:</p> <ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting.<ul> <li>Added recommendation and reasons for <code>Client</code> and <code>Plain</code> styles. #456</li> </ul> </li> <li>Added support for configuration of default module options. #459<ul> <li><code>binding</code> and <code>configuration</code> options can be set to a default value.</li> <li>Updated <code>New-PSRuleOption</code> parameter sets and help based on updates to module config.</li> </ul> </li> <li>Added support for module fallback culture. #441</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed resource schema to include <code>useQualifiedName</code> and <code>nameSeparator</code> option. #458</li> </ul> </li> </ul> <p>What's changed since pre-release v0.17.0-B2005010:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0170-b2005010-pre-release","title":"v0.17.0-B2005010 (pre-release)","text":"<ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting.<ul> <li>Added recommendation and reasons for <code>Client</code> and <code>Plain</code> styles. #456</li> </ul> </li> <li>Added support for configuration of default module options. #459<ul> <li><code>binding</code> and <code>configuration</code> options can be set to a default value.</li> <li>Updated <code>New-PSRuleOption</code> parameter sets and help based on updates to module config.</li> </ul> </li> <li>Added support for module fallback culture. #441</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed resource schema to include <code>useQualifiedName</code> and <code>nameSeparator</code> option. #458</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0160","title":"v0.16.0","text":"<p>What's changed since v0.15.0:</p> <ul> <li>General improvements:<ul> <li>Added configuration option <code>Output.Culture</code> for setting culture. #442</li> <li>Improved handling of fields to allow the input object to be referenced with <code>.</code>. #437</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed numeric comparison assertion with non-int types. #436</li> <li>Fixed output culture option ignored. #449</li> </ul> </li> </ul> <p>What's changed since pre-release v0.16.0-B2003027:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0160-b2003027-pre-release","title":"v0.16.0-B2003027 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed output culture option ignored. #449</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0160-b2003022-pre-release","title":"v0.16.0-B2003022 (pre-release)","text":"<ul> <li>General improvements:<ul> <li>Added configuration option <code>Output.Culture</code> for setting culture. #442</li> <li>Improved handling of fields to allow the input object to be referenced with <code>.</code>. #437</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed numeric comparison assertion with non-int types. #436</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0150","title":"v0.15.0","text":"<p>What's changed since v0.14.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>-ResultVariable</code> to store results from Assert-PSRule into a variable. #412</li> </ul> </li> <li>General improvements:<ul> <li>Added recommendation to failure message of NUnit results. #421</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling of <code>v</code> in field value with <code>$Assert.Version</code>. #429</li> <li>Fixed handling of warning action preference with <code>Assert-PSRule</code>. #428</li> <li>Fixed parent culture unwind with POSIX. #414</li> <li>Fixed output of warning with <code>Assert-PSRule</code>. #417</li> <li>Fixed NUnit report to include a failure element when reason is not specified. #420</li> </ul> </li> </ul> <p>What's changed since pre-release v0.15.0-B2002031:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002031-pre-release","title":"v0.15.0-B2002031 (pre-release)","text":"<ul> <li>Fixed handling of <code>v</code> in field value with <code>$Assert.Version</code>. #429</li> <li>Fixed handling of warning action preference with <code>Assert-PSRule</code>. #428</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002019-pre-release","title":"v0.15.0-B2002019 (pre-release)","text":"<ul> <li>Added <code>-ResultVariable</code> to store results from Assert-PSRule into a variable. #412</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002012-pre-release","title":"v0.15.0-B2002012 (pre-release)","text":"<ul> <li>Fixed output of warning with <code>Assert-PSRule</code>. #417</li> <li>Fixed NUnit report to include a failure element when reason is not specified. #420</li> <li>Added recommendation to failure message of NUnit results. #421</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002005-pre-release","title":"v0.15.0-B2002005 (pre-release)","text":"<ul> <li>Fixed parent culture unwind with POSIX. #414</li> </ul>"},{"location":"CHANGELOG-v0/#v0140","title":"v0.14.0","text":"<p>What's changed since v0.13.0:</p> <ul> <li>Engine features:<ul> <li>Added support for qualified target names. #395<ul> <li>Added options <code>Binding.UseQualifiedName</code> and <code>Binding.NameSeparator</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added assertion method <code>HasJsonSchema</code> to check if a JSON schema is referenced. #398<ul> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Added file content helper for reading objects from files. #399<ul> <li>The method <code>GetContent</code> of <code>$PSRule</code> can be used to read files as objects.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Improved reporting on runtime errors in rule blocks. #239</li> <li>Improved NUnit results to include a failure message based on reported reasons. #404</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed wide formatting of rules with <code>Get-PSRule</code>. #407</li> <li>Fixed TargetName hash serialization for base types. #406</li> <li>Fixed output not generated with Assert-PSRule and Stop. #405</li> <li>Fixed NUnit results incorrectly reporting that the test had not executed. #403</li> </ul> </li> </ul> <p>What's changed since pre-release v0.14.0-B2002003:</p> <ul> <li>No additional changes</li> </ul>"},{"location":"CHANGELOG-v0/#v0140-b2002003-pre-release","title":"v0.14.0-B2002003 (pre-release)","text":"<ul> <li>Fixed wide formatting of rules with <code>Get-PSRule</code>. #407</li> <li>Fixed TargetName hash serialization for base types. #406</li> <li>Fixed output not generated with Assert-PSRule and Stop. #405</li> <li>Fixed NUnit results incorrectly reporting that the test had not executed. #403</li> <li>Improved NUnit results to include a failure message based on reported reasons. #404</li> <li>Improved reporting on runtime errors in rule blocks. #239</li> </ul>"},{"location":"CHANGELOG-v0/#v0140-b2001020-pre-release","title":"v0.14.0-B2001020 (pre-release)","text":"<ul> <li>Added support for qualified target names. #395<ul> <li>Added options <code>Binding.UseQualifiedName</code> and <code>Binding.NameSeparator</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added assertion method <code>HasJsonSchema</code> to check if a JSON schema is referenced. #398<ul> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Added file content helper for reading objects from files. #399<ul> <li>The method <code>GetContent</code> of <code>$PSRule</code> can be used to read files as objects.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130","title":"v0.13.0","text":"<p>What's changed since v0.12.0:</p> <ul> <li>Engine features:<ul> <li>Improvements to rule help and documentation. #382 #316<ul> <li>Added links and notes sections to help.</li> <li>Added <code>-Full</code> switch to <code>Get-PSRuleHelp</code> to display links and notes sections.</li> <li>Added support for using a parent culture in rule help.</li> <li>Rule help will use parent culture when a more specific culture is not available.</li> </ul> </li> <li>Added input format for reading PowerShell data <code>.psd1</code> files. #368<ul> <li><code>PowerShellData</code> has been added to <code>Input.Format</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added custom rule data to results. #322<ul> <li><code>$PSRule.Data</code> can be used to set custom data during rule execution that is included in output.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> <li>Improvements to assertion methods. #386 #374 #387 #344 #353 #357<ul> <li>Added support for assertion methods to be used within script pre-conditions.</li> <li>Added numeric comparison assertion helpers <code>Greater</code>, <code>GreaterOrEqual</code>, <code>Less</code> and <code>LessOrEqual</code>.</li> <li>Added semantic version assertion helper <code>Version</code>.</li> <li>Added string affix assertion helpers <code>StartsWith</code>, <code>EndsWith</code> and <code>Contains</code>.</li> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Improvements to output logging and formatting for <code>Assert-PSRule</code>.<ul> <li>Formatting now includes errors and warnings using style.</li> <li>Added PSRule banner with module information.</li> <li>Added rule success summary.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added aliases for <code>-OutputFormat</code> (<code>-o</code>) and <code>-Module</code> (<code>-m</code>) parameters. #384</li> <li>Added <code>WithReason</code> to append/ replace reasons from assertion result. #354</li> <li>Added configuration helper for strings arrays. #363</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed JSON de-serialization fails with single object. #379</li> <li>Fixed stack overflow when parsing malformed JSON. #380</li> </ul> </li> </ul> <p>What's changed since pre-release v0.13.0-B2001013:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b2001013-pre-release","title":"v0.13.0-B2001013 (pre-release)","text":"<ul> <li>Fixed JSON de-serialization fails with single object. #379</li> <li>Fixed stack overflow when parsing malformed JSON. #380</li> <li>Added rule documentation links and notes to help. #382<ul> <li>Added <code>-Full</code> switch to <code>Get-PSRuleHelp</code> to display links and notes sections.</li> </ul> </li> <li>Added aliases for <code>-OutputFormat</code> (<code>-o</code>) and <code>-Module</code> (<code>-m</code>) parameters. #384</li> <li>Improved numeric comparison assertion helpers to support strings. #387<ul> <li>Methods <code>Greater</code>, <code>GreaterOrEqual</code>, <code>Less</code> and <code>LessOrEqual</code> now also check string length.</li> </ul> </li> <li>Added support for assertion methods to be used within script pre-conditions. #386</li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912043-pre-release","title":"v0.13.0-B1912043 (pre-release)","text":"<ul> <li>Added input format for reading PowerShell data <code>.psd1</code> files. #368<ul> <li><code>PowerShellData</code> has been added to <code>Input.Format</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added numeric comparison assertion helpers. #374<ul> <li>Added methods <code>Greater</code>, <code>GreaterOrEqual</code>, <code>Less</code> and <code>LessOrEqual</code>.</li> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912027-pre-release","title":"v0.13.0-B1912027 (pre-release)","text":"<ul> <li>Added configuration helper for strings arrays. #363</li> <li>Added support for using a parent culture in rule help. #316<ul> <li>Rule help will use parent culture when a more specific culture is not available.</li> </ul> </li> <li>Added custom rule data to results. #322<ul> <li><code>$PSRule.Data</code> can be used to set custom data during rule execution that is included in output.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912012-pre-release","title":"v0.13.0-B1912012 (pre-release)","text":"<ul> <li>Improves output logging and formatting for Assert-PSRule. #357<ul> <li>Formatting now includes errors and warnings using style.</li> <li>Added PSRule banner with module information.</li> <li>Added rule success summary.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912005-pre-release","title":"v0.13.0-B1912005 (pre-release)","text":"<ul> <li>Added semantic version assertion helper <code>Version</code>. #344</li> <li>Added string affix assertion helpers. #353<ul> <li>Added methods <code>StartsWith</code>, <code>EndsWith</code> and <code>Contains</code>. See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Added <code>WithReason</code> to append/ replace reasons from assertion result. #354</li> </ul>"},{"location":"CHANGELOG-v0/#v0120","title":"v0.12.0","text":"<p>What's changed since v0.11.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>-All</code> option to <code>Exists</code> keyword. #331</li> <li>Added custom field binding. #321<ul> <li>Added new option <code>Binding.Field</code> available in baselines to configure binding.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added filtering for rules against a baseline with <code>Get-PSRule</code>. #345</li> <li>Added parameter alias <code>-f</code> for <code>-InputPath</code>. #340<ul> <li><code>-f</code> was added to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code> cmdlets.</li> </ul> </li> </ul> </li> <li>Important change: Added <code>$PSRule</code> generic context variable. #341<ul> <li>Deprecated <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> properties on <code>$Rule</code>.</li> <li>Use <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$PSRule</code> instead.</li> <li>Properties <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$Rule</code> will be removed in the future.</li> <li>Going forward <code>$Rule</code> will only contain properties that relate to the current rule context.</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed key has already been added for default baseline. #349</li> <li>Fixed multiple value tag filtering. #346</li> <li>Fixed TargetType fall back to type name. #339</li> <li>Fixed NUnit serialization issue for unprocessed rules. #332</li> </ul> </li> </ul> <p>What's changed since pre-release v0.12.0-B1912007:</p> <ul> <li>Fixed key has already been added for default baseline. #349</li> </ul>"},{"location":"CHANGELOG-v0/#v0120-b1912007-pre-release","title":"v0.12.0-B1912007 (pre-release)","text":"<ul> <li>Fixed multiple value tag filtering. #346</li> <li>Added filtering for rules against a baseline with <code>Get-PSRule</code>. #345</li> </ul>"},{"location":"CHANGELOG-v0/#v0120-b1912002-pre-release","title":"v0.12.0-B1912002 (pre-release)","text":"<ul> <li>Fixed TargetType fall back to type name. #339</li> <li>Added custom field binding. #321<ul> <li>Added new option <code>Binding.Field</code> available in baselines to configure binding.</li> </ul> </li> <li>Added parameter alias <code>-f</code> for <code>-InputPath</code>. #340<ul> <li><code>-f</code> was added to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code> cmdlets.</li> </ul> </li> <li>Important change: Added <code>$PSRule</code> generic context variable. #341<ul> <li>Deprecated <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> properties on <code>$Rule</code>.</li> <li>Use <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$PSRule</code> instead.</li> <li>Properties <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$Rule</code> will be removed in the future.</li> <li>Going forward <code>$Rule</code> will only contain properties that relate to the current rule context.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0120-b1911013-pre-release","title":"v0.12.0-B1911013 (pre-release)","text":"<ul> <li>Fixed NUnit serialization issue for unprocessed rules. #332</li> <li>Added <code>-All</code> option to <code>Exists</code> keyword. #331</li> </ul>"},{"location":"CHANGELOG-v0/#v0110","title":"v0.11.0","text":"<p>What's changed since v0.10.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>-TargetType</code> parameter to filter input objects by target type. #176<ul> <li>This parameter applies to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code>.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed null reference exception when bound property is null. #323</li> <li>Fixed missing <code>Markdown</code> input format in options schema. #315</li> </ul> </li> <li>Breaking change: Unprocessed object results are not returned from <code>Test-PSRuleTarget</code> by default. #318<ul> <li>Previously unprocessed objects returned <code>$True</code>, now unprocessed objects return no result.</li> <li>Use <code>-Outcome All</code> to return <code>$True</code> for unprocessed objects the same as &lt;= v0.10.0.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.11.0-B1911002:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0110-b1911002-pre-release","title":"v0.11.0-B1911002 (pre-release)","text":"<ul> <li>Fixed null reference exception when bound property is null. #323</li> </ul>"},{"location":"CHANGELOG-v0/#v0110-b1910014-pre-release","title":"v0.11.0-B1910014 (pre-release)","text":"<ul> <li>Fixed missing <code>Markdown</code> input format in options schema. #315</li> <li>Added <code>-TargetType</code> parameter to filter input objects by target type. #176<ul> <li>This parameter applies to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code>.</li> </ul> </li> <li>Breaking change: Unprocessed object results are not returned from <code>Test-PSRuleTarget</code> by default. #318<ul> <li>Previously unprocessed objects returned <code>$True</code>, now unprocessed objects return no result.</li> <li>Use <code>-Outcome All</code> to return <code>$True</code> for unprocessed objects the same as &lt;= v0.10.0.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0100","title":"v0.10.0","text":"<p>What's changed since v0.9.0:</p> <ul> <li>General improvements:<ul> <li>Added source note properties to input objects read from disk with <code>-InputPath</code>. #302</li> </ul> </li> <li>Engine features:<ul> <li>Added assertion helper for checking field default value. #289</li> <li>Added dependency <code>DependsOn</code> information to results from <code>Get-PSRule</code>. #210<ul> <li>To include dependencies that would normally be filtered out use <code>-IncludeDependencies</code>.</li> </ul> </li> <li>Added input format for reading markdown front matter. #301<ul> <li>Markdown front matter is deserialized and evaluated as an object.</li> </ul> </li> <li>Added <code>Assert-PSRule</code> cmdlet to improve integration into CI processes. #290<ul> <li>Added <code>Output.Style</code> option to support output in the following styles:<ul> <li>Client/ Plain - Output returns easy to read log of rule pass/ fail.</li> <li>Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.</li> <li>GitHub Actions - Reports rule failures as errors collected by GitHub Actions.</li> </ul> </li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fix <code>Get-PSRuleHelp</code> -Online in constrained language mode. #296</li> </ul> </li> <li>Breaking change: Removed previously deprecated alias <code>Hint</code> for <code>Recommend</code>. #165<ul> <li>Use the <code>Recommend</code> keyword instead.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.10.0-B1910036:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0100-b1910036-pre-release","title":"v0.10.0-B1910036 (pre-release)","text":"<ul> <li>Added dependency <code>DependsOn</code> information to results from <code>Get-PSRule</code>. #210<ul> <li>To include dependencies that would normally be filtered out use <code>-IncludeDependencies</code>.</li> </ul> </li> <li>Added input format for reading markdown front matter. #301<ul> <li>Markdown front matter is deserialized and evaluated as an object.</li> </ul> </li> <li>Added source note properties to input objects read from disk with <code>-InputPath</code>. #302</li> <li>Breaking change: Removed previously deprecated alias <code>Hint</code> for <code>Recommend</code>. #165<ul> <li>Use the <code>Recommend</code> keyword instead.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0100-b1910025-pre-release","title":"v0.10.0-B1910025 (pre-release)","text":"<ul> <li>Fix <code>Get-PSRuleHelp</code> -Online in constrained language mode. #296</li> <li>Added <code>Assert-PSRule</code> cmdlet to improve integration into CI processes. #290<ul> <li>Added <code>Output.Style</code> option to support output in the following styles:<ul> <li>Client/ Plain - Output returns easy to read log of rule pass/ fail.</li> <li>Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.</li> <li>GitHub Actions - Reports rule failures as errors collected by GitHub Actions.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0100-b1910011-pre-release","title":"v0.10.0-B1910011 (pre-release)","text":"<ul> <li>Added assertion helper for checking field default value. #289</li> </ul>"},{"location":"CHANGELOG-v0/#v090","title":"v0.9.0","text":"<p>What's changed since v0.8.0:</p> <ul> <li>General improvements:<ul> <li>Improve feedback of parsing errors. #185</li> <li>Updated <code>Get-PSRuleHelp</code> to include help within the current path by default. #197</li> </ul> </li> <li>Engine features:<ul> <li>Added support for a wildcard match using the <code>Within</code> keyword. #272</li> <li>Added rule info display name. #276</li> <li>Added support for matching an array of tag values. #282</li> <li>Added named baselines. Now baselines are a separate resource that can be individually used.<ul> <li>Baselines can be packaged within module.</li> <li>Modules can specify a default baseline in module manifest.</li> <li>Target binding options (<code>Binding</code>) are now part of baselines.</li> <li>See about_PSRule_Baseline for more information.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fix can not serialize nested System.IO.DirectoryInfo property. #281</li> <li>Fix ModuleName not displayed in Get-PSRuleHelp list. #275</li> <li>Fix outcome reported when error or exception is raised. #211</li> </ul> </li> <li>Breaking change: Baseline improvements, fundamentally changes how baselines work. #274<ul> <li>Previously, baselines were specified as workspace options.</li> <li>The previous <code>baseline</code> options property has been renamed to <code>rule</code>.</li> <li>The previous <code>configuration</code> property is now a top level option.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.9.0-B190905:</p> <ul> <li>No additional changes</li> </ul>"},{"location":"CHANGELOG-v0/#v090-b190905-pre-release","title":"v0.9.0-B190905 (pre-release)","text":"<ul> <li>Added support for matching an array of tag values. #282</li> <li>Updated <code>Get-PSRuleHelp</code> to include help within the current path by default. #197</li> <li>Fix can not serialize nested System.IO.DirectoryInfo property. #281</li> <li>Fix export of <code>Like</code> parameter for <code>Within</code> keyword. #279</li> <li>Breaking change: Added named baselines. This changes how baselines work. #274<ul> <li>Previously, baselines were specified as workspace options.</li> <li>Now, baselines are a separate resource that can be individually used. Additionally:<ul> <li>Baselines can be packaged within module.</li> <li>Modules can specify a default baseline in module manifest.</li> <li>Target binding options (<code>Binding</code>) are now part of baselines.</li> </ul> </li> <li>The previous <code>baseline</code> options property has been renamed to <code>rule</code>.</li> <li>The previous <code>configuration</code> property is now a top level option.</li> <li>See about_PSRule_Baseline for more information.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v090-b190819-pre-release","title":"v0.9.0-B190819 (pre-release)","text":"<ul> <li>Added support for a wildcard match using the <code>Within</code> keyword. #272</li> <li>Added rule info display name. #276</li> <li>Fix ModuleName not displayed in Get-PSRuleHelp list. #275</li> </ul>"},{"location":"CHANGELOG-v0/#v090-b190810-pre-release","title":"v0.9.0-B190810 (pre-release)","text":"<ul> <li>Improve feedback of parsing errors. #185</li> <li>Fix outcome reported when error or exception is raised. #211</li> </ul>"},{"location":"CHANGELOG-v0/#v080","title":"v0.8.0","text":"<p>What's changed since v0.7.0:</p> <ul> <li>General improvements:<ul> <li>PSRule options are now displayed as YAML instead of a complex object. #233</li> <li>Add detection for improper keyword use. #203</li> <li>Automatically load rule modules. #218</li> <li>Added support for debug messages and <code>Write-Debug</code> in rule definitions. #146</li> <li>Added <code>Logging.LimitDebug</code> and <code>Logging.LimitVerbose</code> options to limit logging to named scopes. #235</li> </ul> </li> <li>Engine features:<ul> <li>Added per object reason for failing rules. #200<ul> <li>Keywords <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> automatically add a reason when they fail.</li> <li>Custom reason can be set for keywords <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> with <code>-Reason</code>.</li> <li>Added <code>Reason</code> keyword to add to reason for custom logic.</li> <li>Added wide output display for <code>Invoke-PSRule</code> which include the reason why rule failed.<ul> <li>To use wide output use the <code>-OutputFormat Wide</code> parameter.</li> </ul> </li> <li>Renamed <code>-Message</code> parameter to <code>-Text</code> on the <code>Recommend</code> keyword.<ul> <li>The <code>-Message</code> is an alias of <code>-Text</code> and will be deprecated in the future.</li> </ul> </li> </ul> </li> <li>Added assertion helper <code>$Assert</code> for extensibility. #250<ul> <li>Add built-in assertions for <code>HasField</code>, <code>HasFieldValue</code> and <code>NullOrEmpty</code>.</li> <li>Add JSON schema assertion method <code>JsonSchema</code>. #42</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fix rule synopsis comment capture. #214</li> <li>Fix YAML options file discovery issue in dotted directory. #232</li> <li>Fix comparison of wrapped types and null with <code>Within</code>. #237</li> </ul> </li> <li>Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217<ul> <li>Rule names have to be unique within the current execution path or within a module.<ul> <li>Previously rule names only had to be unique within a single file.</li> </ul> </li> <li>Previously the <code>filename.rule.ps1/RuleName</code> was required to reference rules across files.<ul> <li>This is no longer required because rule names are unique.</li> </ul> </li> <li>You can reference a rule from a loaded module by using the syntax <code>ModuleName\\RuleName</code>.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.8.0-B190806:</p> <ul> <li>Fix export of assertion helper variable <code>$Assert</code>. #262</li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190806-pre-release","title":"v0.8.0-B190806 (pre-release)","text":"<ul> <li>Fix module reloading with different versions. #254</li> <li>Fix not finding rules in current path by default. #256</li> <li>Fix rule synopsis comment capture. #214</li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190742-pre-release","title":"v0.8.0-B190742 (pre-release)","text":"<ul> <li>Fix inconsistent handling of <code>$PWD</code>. #249</li> <li>Add detection for improper keyword use. #203</li> <li>Automatically load rule modules. #218</li> <li>Added assertion helper <code>$Assert</code> for extensibility. #250<ul> <li>Add built-in assertions for <code>HasField</code>, <code>HasFieldValue</code> and <code>NullOrEmpty</code>.</li> <li>Add JSON schema assertion method <code>JsonSchema</code>. #42</li> </ul> </li> <li>Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217<ul> <li>Rule names have to be unique within the current execution path or within a module.<ul> <li>Previously rule names only had to be unique within a single file.</li> </ul> </li> <li>Previously the <code>filename.rule.ps1/RuleName</code> was required to reference rules across files.<ul> <li>This is no longer required because rule names are unique.</li> </ul> </li> <li>You can reference a rule from a loaded module by using the syntax <code>ModuleName\\RuleName</code>.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190716-pre-release","title":"v0.8.0-B190716 (pre-release)","text":"<ul> <li>Added per object reason for failing rules. #200<ul> <li>The keywords <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> automatically add a reason when they fail.</li> <li>Added <code>-Reason</code> parameter to <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> keywords to allow a custom reason to be set.</li> <li>Added <code>Reason</code> keyword to add to reason for custom logic.</li> <li>Added wide output display for <code>Invoke-PSRule</code> which include the reason why rule failed.<ul> <li>To use wide output use the <code>-OutputFormat Wide</code> parameter.</li> </ul> </li> <li>Renamed <code>-Message</code> parameter to <code>-Text</code> on the <code>Recommend</code> keyword.<ul> <li>The <code>-Message</code> is an alias of <code>-Text</code> and will be deprecated in the future.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190708-pre-release","title":"v0.8.0-B190708 (pre-release)","text":"<ul> <li>Fix YAML options file discovery issue in dotted directory. #232</li> <li>Fix comparison of wrapped types and null with <code>Within</code>. #237</li> <li>PSRule options are now displayed as YAML instead of a complex object. #233</li> <li>Added support for debug messages and <code>Write-Debug</code> in rule definitions. #146</li> <li>Added <code>Logging.LimitDebug</code> and <code>Logging.LimitVerbose</code> options to limit logging to named scopes. #235</li> </ul>"},{"location":"CHANGELOG-v0/#v070","title":"v0.7.0","text":"<p>What's changed since v0.6.0:</p> <ul> <li>Fix reading nested arrays from JSON input. #223</li> <li>Fix comparison of non-string types with <code>Within</code>. #226</li> <li>Fix circular rule dependency issue. #190</li> <li>Fix rule <code>DependsOn</code> parameter allows null. #191</li> <li>Fix error message when attempting to use the rule keyword in a rule definition. #189</li> <li>Fix TargetName binding when TargetName or Name property is null. #202</li> <li>Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187 #224</li> <li>Include .ps1 files that are specified directly with <code>-Path</code>, instead of only .Rule.ps1 files. #182<ul> <li>Improved warning message displayed when no Rule.ps1 files are founds.</li> </ul> </li> <li>Added support for <code>Invoke-PSRule</code> to return CSV formatted results. #169<ul> <li>To generate CSV results use the <code>-OutputFormat Csv</code> parameter.</li> <li>Added <code>Output.Path</code> option to allow output to be saved directly to file.</li> <li>Added <code>Output.Encoding</code> option configure encoding used to write to file.</li> <li>By default, UTF-8 encoding without BOM is used.</li> <li><code>Invoke-PSRule</code> cmdlet also provides a parameter <code>-OutputPath</code> to write results to file.</li> </ul> </li> <li>Reordered cmdlet parameters to improve usage of frequently used parameters. #175<ul> <li><code>-Module</code> parameter will tab-complete with imported rule modules.</li> </ul> </li> <li>Added culture support for PowerShell informational messages. #158<ul> <li>A new <code>$LocalizedData</code> variable can be used within rule definitions.</li> </ul> </li> <li>Added <code>-Not</code> switch to <code>Within</code> and <code>Match</code> keywords to allow negative comparison. #208</li> <li>Improve discovery of rule tags. #209<ul> <li>Add wide format <code>-OutputFormat Wide</code> to <code>Get-PSRule</code> to allow output of rule tags.</li> </ul> </li> <li>Breaking change: Changed rule filtering by tag to be case-insensitive. #204<ul> <li>Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.</li> </ul> </li> <li>Breaking change: Rule time is recorded in milliseconds instead of seconds. #192</li> </ul> <p>What's changed since pre-release v0.7.0-B190664:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190664-pre-release","title":"v0.7.0-B190664 (pre-release)","text":"<ul> <li>Fix reading nested arrays from JSON input. #223</li> <li>Fix comparison of non-string types with <code>Within</code>. #226</li> <li>Improve handling of null rule result. #224</li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190652-pre-release","title":"v0.7.0-B190652 (pre-release)","text":"<ul> <li>Fix TargetName binding when TargetName or Name property is null. #202</li> <li>Add culture support for PowerShell informational messages. #158<ul> <li>A new <code>$LocalizedData</code> variable can be used within rule definitions.</li> </ul> </li> <li>Add <code>-Not</code> switch to <code>Within</code> and <code>Match</code> keywords to allow negative comparison. #208</li> <li>Improve discovery of rule tags. #209<ul> <li>Add wide format <code>-OutputFormat Wide</code> to <code>Get-PSRule</code> to allow output of rule tags.</li> </ul> </li> <li>Breaking change: Change rule filtering by tag to be case-insensitive. #204<ul> <li>Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190633-pre-release","title":"v0.7.0-B190633 (pre-release)","text":"<ul> <li>Fix circular rule dependency issue. #190</li> <li>Fix rule <code>DependsOn</code> parameter allows null. #191</li> <li>Fix error message when attempting to use the rule keyword in a rule definition. #189</li> <li>Breaking change: Rule time is recorded in milliseconds instead of seconds. #192</li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190624-pre-release","title":"v0.7.0-B190624 (pre-release)","text":"<ul> <li>Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187</li> <li>Include .ps1 files that are specified directly with <code>-Path</code>, instead of only .rule.ps1 files. #182<ul> <li>Improved warning message displayed when no Rule.ps1 files are founds.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190613-pre-release","title":"v0.7.0-B190613 (pre-release)","text":"<ul> <li>Added support for <code>Invoke-PSRule</code> to return CSV formatted results. #169<ul> <li>To generate CSV results use the <code>-OutputFormat Csv</code> parameter.</li> <li>Added <code>Output.Path</code> option to allow output to be saved directly to file.</li> <li>Added <code>Output.Encoding</code> option configure encoding used to write to file.</li> <li>By default, UTF-8 encoding without BOM is used.</li> <li><code>Invoke-PSRule</code> cmdlet also provides a parameter <code>-OutputPath</code> to write results to file.</li> </ul> </li> <li>Reordered cmdlet parameters to improve usage of frequently used parameters. #175<ul> <li><code>-Module</code> parameter will tab-complete with imported rule modules.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v060","title":"v0.6.0","text":"<p>What's changed since v0.5.0:</p> <ul> <li>Fix operation is not supported on this platform failure. #152</li> <li>Fix FullName cannot be found on this object error. #149</li> <li>Fix discovery of rules within paths that contain spaces fails. #168</li> <li>Added rule documentation, which allows additional rule information to be stored in markdown files. #157<ul> <li>Rule documentation also adds culture support. #18</li> <li>Rule documentation can be accessed like help with the <code>Get-PSRuleHelp</code> cmdlet.</li> </ul> </li> <li>Added annotations, which are non-indexed metadata stored in rule documentation. #148<ul> <li>Annotations can contain a link to online version of the documentation. #147</li> </ul> </li> <li>Important change: Changed <code>Hint</code> keyword to <code>Recommend</code> to align with rule documentation. #165<ul> <li>Use of <code>Hint</code> keyword is deprecated and will be removed in a future release. Currently <code>Hint</code> is aliased to <code>Recommend</code> for compatibility.</li> </ul> </li> <li>Breaking change: Changed rule properties to align with rule documentation. #164<ul> <li>Rule <code>Synopsis</code>, is a brief summary of the rule and <code>Description</code> is a detailed purpose of the rule.</li> <li><code>Description:</code> metadata keyword used in comment help is now <code>Synopsis:</code>, use of <code>Description:</code> will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.</li> <li>Output property <code>Message</code> on rule results is now <code>Recommendation</code>.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.6.0-B190627:</p> <ul> <li>Fix discovery of rules within paths that contain spaces fails. #168</li> <li>Fix exporting of <code>Recommend</code> keyword and <code>Hint</code> alias. #171</li> </ul>"},{"location":"CHANGELOG-v0/#v060-b190627-pre-release","title":"v0.6.0-B190627 (pre-release)","text":"<ul> <li>Important change: Changed <code>Hint</code> keyword to <code>Recommend</code> to align with rule documentation. #165<ul> <li>Use of <code>Hint</code> keyword is deprecated and will be removed in a future release. Currently <code>Hint</code> is aliased to <code>Recommend</code> for compatibility.</li> </ul> </li> <li>Breaking change: Changed rule properties to align with rule documentation. #164<ul> <li>Rule <code>Synopsis</code>, is a brief summary of the rule and <code>Description</code> is a detailed purpose of the rule.</li> <li><code>Description:</code> metadata keyword used in comment help is now <code>Synopsis:</code>, use of <code>Description:</code> will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.</li> <li>Output property <code>Message</code> on rule results is now <code>Recommendation</code>.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v060-b190614-pre-release","title":"v0.6.0-B190614 (pre-release)","text":"<ul> <li>Added rule documentation, which allows additional rule information to be stored in markdown files. #157<ul> <li>Rule documentation also adds culture support. #18</li> <li>Rule documentation can be accessed like help with the <code>Get-PSRuleHelp</code> cmdlet.</li> </ul> </li> <li>Added annotations, which are non-indexed metadata stored in rule documentation. #148<ul> <li>Annotations can contain a link to online version of the documentation. #147</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v060-b190514-pre-release","title":"v0.6.0-B190514 (pre-release)","text":"<ul> <li>Fix operation is not supported on this platform failure. #152</li> <li>Fix FullName cannot be found on this object error. #149</li> </ul>"},{"location":"CHANGELOG-v0/#v050","title":"v0.5.0","text":"<p>What's changed since v0.4.0:</p> <ul> <li>Fix PSRule options schema usage of additionalProperties. #136</li> <li>Fix null reference exception when traversing null field. #123</li> <li>Fix missing help topics for options and variables. #125</li> <li>Improved handling of default YAML options file. #137</li> <li>Added support for <code>Invoke-PSRule</code> to return NUnit3 formatted results. #129<ul> <li>To generate NUnit3 results use the <code>-OutputFormat NUnit3</code> parameter.</li> </ul> </li> <li>Added <code>Set-PSRuleOption</code> cmdlet to configure YAML options file. #135</li> <li>Added parameters to New-PSRuleOption to configure common options. #134<ul> <li>Additional parameters are an alternative to using a <code>-Option</code> hashtable.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.5.0-B190423:</p> <ul> <li>Fix schema conformance of <code>-OutputFormat NUnit3</code> to NUnit report schema. #141</li> <li>Fix PSRule options schema usage of additionalProperties. #136</li> </ul>"},{"location":"CHANGELOG-v0/#v050-b190423-pre-release","title":"v0.5.0-B190423 (pre-release)","text":"<ul> <li>Added support for <code>Invoke-PSRule</code> to return NUnit3 formatted results. #129<ul> <li>To generate NUnit3 results use the <code>-OutputFormat NUnit3</code> parameter.</li> </ul> </li> <li>Added <code>Set-PSRuleOption</code> cmdlet to configure YAML options file. #135</li> <li>Added parameters to New-PSRuleOption to configure common options. #134<ul> <li>Additional parameters are an alternative to using a <code>-Option</code> hashtable.</li> </ul> </li> <li>Improved handling of default YAML options file. #137</li> </ul>"},{"location":"CHANGELOG-v0/#v050-b190405-pre-release","title":"v0.5.0-B190405 (pre-release)","text":"<ul> <li>Fix null reference exception when traversing null field. #123</li> <li>Fix missing help topics for options and variables. #125</li> </ul>"},{"location":"CHANGELOG-v0/#v040","title":"v0.4.0","text":"<p>What's changed since v0.3.0:</p> <ul> <li>Fix incorrect JSON de-serialization. #109 #111</li> <li>Added support for using <code>-InputPath</code> instead of using <code>-InputObject</code> to handle serialized objects. #106<ul> <li><code>-Format</code> is automatically detected for <code>.yaml</code>, <code>.yml</code> and <code>.json</code> file extensions.</li> </ul> </li> <li>Added <code>-OutputFormat</code> parameter to serialize output from <code>Invoke-PSRule</code> as YAML or JSON. #29</li> <li>Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97</li> <li>Breaking change: Deprecated usage of the <code>-TargetName</code> parameter on the <code>Hint</code> keyword has been removed. #81</li> </ul> <p>What's changed since pre-release v0.4.0-B190328:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v040-b190328-pre-release","title":"v0.4.0-B190328 (pre-release)","text":"<ul> <li>Fix summary is not correctly serialized with JSON or YAML output format. #116</li> <li>Fix missing properties on serialized YAML output. #115</li> <li>Fix incorrect property name case of YAML serialized results. #114</li> </ul>"},{"location":"CHANGELOG-v0/#v040-b190320-pre-release","title":"v0.4.0-B190320 (pre-release)","text":"<ul> <li>Fix incorrect JSON de-serialization of nested arrays. #109</li> <li>Fix incorrect JSON de-serialization of non-object arrays. #111</li> </ul>"},{"location":"CHANGELOG-v0/#v040-b190311-pre-release","title":"v0.4.0-B190311 (pre-release)","text":"<ul> <li>Added support for using <code>-InputPath</code> instead of using <code>-InputObject</code> to handle serialized objects. #106<ul> <li><code>-Format</code> is automatically detected for <code>.yaml</code>, <code>.yml</code> and <code>.json</code> file extensions.</li> </ul> </li> <li>Added <code>-OutputFormat</code> parameter to serialize output from <code>Invoke-PSRule</code>. #29</li> <li>Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97</li> <li>Breaking change: Deprecated usage of the <code>-TargetName</code> parameter on the <code>Hint</code> keyword has been removed. #81</li> </ul>"},{"location":"CHANGELOG-v0/#v030","title":"v0.3.0","text":"<p>What's changed since v0.2.0:</p> <ul> <li>Added support for pipelining with <code>Exists</code>, <code>Within</code>, <code>Match</code> and <code>TypeOf</code> keywords #90</li> <li>Added support for packaging rules in modules #16</li> <li>Import objects from YAML or JSON format #75<ul> <li>Added support for input de-serialization from FileInfo objects #95</li> </ul> </li> <li>Support nested TargetObjects #77</li> <li>Export variables to improve authoring experience #83</li> <li>Binding improvements:<ul> <li>Added object type binding and dynamic filtering for rules #82</li> <li>Added support for indexed and quoted field names #86</li> <li>Added support for case-sensitive binding operations #87<ul> <li>Binding ignores case by default. Set option <code>Binding.CaseSensitive</code> to <code>true</code> to enable case-sensitivity.</li> </ul> </li> <li>Support TargetName binding of nested properties #71</li> </ul> </li> <li>Added online help links to keywords #72</li> <li>Added schema for PSRule options #74</li> <li>Important change: The <code>-TargetName</code> parameter of the <code>Hint</code> keyword has been deprecated #81<ul> <li><code>-TargetName</code> parameter not longer sets the pipeline object TargetName and generates a warning instead.</li> <li>The <code>-TargetName</code> will be completely removed in v0.4.0, at which time using the parameter will generate an error.</li> </ul> </li> <li>Breaking change: Changed parameter alias for <code>-Path</code> from <code>-f</code> to <code>-p</code> #99</li> </ul> <p>What's changed since pre-release v0.3.0-B190231:</p> <ul> <li>Added support for input de-serialization from FileInfo objects #95</li> <li>Breaking change: Changed parameter alias for <code>-Path</code> from <code>-f</code> to <code>-p</code> #99</li> </ul>"},{"location":"CHANGELOG-v0/#v030-b190231-pre-release","title":"v0.3.0-B190231 (pre-release)","text":"<ul> <li>Added support for pipelining with <code>Exists</code>, <code>Within</code>, <code>Match</code> and <code>TypeOf</code> keywords #90</li> <li>Fix empty YAML object causes format de-serialize to fail #92</li> </ul>"},{"location":"CHANGELOG-v0/#v030-b190224-pre-release","title":"v0.3.0-B190224 (pre-release)","text":"<ul> <li>Export variables to improve authoring experience #83</li> <li>Added support for packaging rules in modules #16</li> <li>Added support for indexed and quoted field names #86</li> <li>Added object type binding and dynamic filtering for rules #82</li> <li>Added support for case-sensitive binding operations #87<ul> <li>Binding ignores case by default. Set option <code>Binding.CaseSensitive</code> to <code>true</code> to enable case-sensitivity.</li> </ul> </li> <li>Important change: The <code>-TargetName</code> parameter of the <code>Hint</code> keyword has been deprecated #81<ul> <li><code>-TargetName</code> parameter not longer sets the pipeline object TargetName and generates a warning instead.</li> <li>The <code>-TargetName</code> will be completely removed in v0.4.0, at which time using the parameter will generate an error.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v030-b190208-pre-release","title":"v0.3.0-B190208 (pre-release)","text":"<ul> <li>Added online help links to keywords #72</li> <li>Added schema for PSRule options #74</li> <li>Import objects from YAML or JSON format #75</li> <li>Support TargetName binding of nested properties #71</li> <li>Support nested TargetObjects #77</li> </ul>"},{"location":"CHANGELOG-v0/#v020","title":"v0.2.0","text":"<p>What's changed since v0.1.0:</p> <ul> <li>Added support for cross-platform environments (Windows, Linux and macOS) #49</li> <li>Added support for nested field names with <code>Exists</code>, <code>Within</code> and <code>Match</code> keywords #60</li> <li>Added support for rule configuration using baselines #17</li> <li>Use rule description when hint message not set #61</li> <li>Allow objects to be suppressed by TargetName for individual rules #13</li> <li>Allow binding of TargetName to custom property #44</li> <li>Custom functions can be used to bind TargetName #44</li> <li>Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44</li> <li>Added <code>Test-PSRuleTarget</code> command to return an overall <code>$True</code> or <code>$False</code> after evaluating rules for an object #30</li> <li>Improve reporting of inconclusive results and objects that are not processed by any rule #46<ul> <li>Inconclusive results and objects not processed will return a warning by default.</li> </ul> </li> <li>Fix propagation of informational messages to host from rule scripts and definitions #48</li> <li>Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53</li> <li>Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54</li> </ul> <p>What's changed since pre-release v0.2.0-B190121:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v020-b190121-pre-release","title":"v0.2.0-B190121 (pre-release)","text":"<ul> <li>Added support for nested field names with <code>Exists</code>, <code>Within</code> and <code>Match</code> keywords #60</li> <li>Added support for rule configuration using baselines #17</li> <li>Use rule description when hint message not set #61</li> </ul>"},{"location":"CHANGELOG-v0/#v020-b190113-pre-release","title":"v0.2.0-B190113 (pre-release)","text":"<ul> <li>Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53</li> <li>Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54</li> <li>Breaking change: Renamed <code>Test-PSRule</code> cmdlet to <code>Test-PSRuleTarget</code> which aligns more closely to the verb-noun naming standard #57</li> </ul>"},{"location":"CHANGELOG-v0/#v020-b190105-pre-release","title":"v0.2.0-B190105 (pre-release)","text":"<ul> <li>Allow objects to be suppressed by TargetName for individual rules #13</li> <li>Allow binding of TargetName to custom property #44</li> <li>Custom functions can be used to bind TargetName #44</li> <li>Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44</li> <li>Added <code>Test-PSRule</code> command to return an overall <code>$True</code> or <code>$False</code> after evaluating rules for an object #30</li> <li>Improve reporting of inconclusive results and objects that are not processed by any rule #46<ul> <li>Inconclusive results and objects not processed will return a warning by default.</li> </ul> </li> <li>Fix propagation of informational messages to host from rule scripts and definitions #48</li> <li>Added support for cross-platform environments (Windows, Linux and macOS) #49</li> </ul>"},{"location":"CHANGELOG-v0/#v010","title":"v0.1.0","text":"<ul> <li>Initial release</li> </ul> <p>What's changed since pre-release v0.1.0-B181235:</p> <ul> <li>Fix outcome filtering of summary results #33</li> <li>Fix target object counter in verbose logging #35</li> <li>Fix hashtable keys should be handled as fields #36</li> </ul>"},{"location":"CHANGELOG-v0/#v010-b181235-pre-release","title":"v0.1.0-B181235 (pre-release)","text":"<ul> <li>RuleId and RuleName are now independent. Rules are created with a name, and the RuleId is generated based on rule name and file name<ul> <li>Rules with the same name can exist and be cross linked with DependsOn, as long a the script file name is different</li> </ul> </li> <li>Added <code>-Not</code> to <code>Exists</code> keyword</li> <li>Improved verbose logging of <code>Exists</code>, <code>AllOf</code>, <code>AnyOf</code> keywords and core engine</li> <li>Breaking change: Renamed outcome filtering parameters to align to type name and increase clarity<ul> <li><code>Invoke-PSRule</code> has a <code>-Outcome</code> parameter instead of <code>-Status</code></li> <li><code>-Outcome</code> supports values of <code>Pass</code>, <code>Fail</code>, <code>Error</code>, <code>None</code>, <code>Processed</code> and <code>All</code></li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v010-b181222-pre-release","title":"v0.1.0-B181222 (pre-release)","text":"<ul> <li>Added rule tags to results to enable grouping and sorting #14</li> <li>Added support to check for rule tag existence. Use <code>*</code> for tag value on <code>-Tag</code> parameter with <code>Invoke-PSRule</code> and <code>Get-PSRule</code></li> <li>Added option to report rule summary using <code>-As</code> parameter of <code>Invoke-PSRule</code> #12</li> </ul>"},{"location":"CHANGELOG-v0/#v010-b181212-pre-release","title":"v0.1.0-B181212 (pre-release)","text":"<ul> <li>Initial pre-release.</li> </ul>"},{"location":"CHANGELOG-v1/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Important notes:</p> <ul> <li>YAML resources will require an <code>apiVersion</code> from PSRule v2. #648</li> <li>Setting the default module baseline requires a module configuration from PSRule v2. #809</li> <li>Resource names have naming restrictions introduced from PSRule v2. #1012</li> </ul> <p>Attention</p> <p>PSRule v1 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.</p>"},{"location":"CHANGELOG-v1/#v1111","title":"v1.11.1","text":"<p>What's changed since v1.11.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed broken documentation links. #980</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v1110","title":"v1.11.0","text":"<p>What's changed since v1.10.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>version</code> expression to check semantic version constraints. #861<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> <li>Added <code>hasDefault</code> expression to check field default value. #870<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>GetReason()</code> not returning results for a failed assertion. #874</li> </ul> </li> </ul> <p>What's changed since pre-release v1.11.0-B2112016:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v1110-b2112016-pre-release","title":"v1.11.0-B2112016 (pre-release)","text":"<p>What's changed since v1.10.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>version</code> expression to check semantic version constraints. #861<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> <li>Added <code>hasDefault</code> expression to check field default value. #870<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>GetReason()</code> not returning results for a failed assertion. #874</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v1100","title":"v1.10.0","text":"<p>What's changed since v1.9.0:</p> <ul> <li>General improvements:<ul> <li>Added JSON support for reading rules and selectors from pipeline. #857</li> <li>Added <code>HasSchema</code> expression to check the schema of an object. #860<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.SourceLink.GitHub to 1.1.1. #856</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>$Assert.HasJsonSchema</code> accepts empty value. #859</li> <li>Fixed module configuration is not loaded when case does not match. #864</li> </ul> </li> </ul> <p>What's changed since pre-release v1.10.0-B2112002:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v1100-b2112002-pre-release","title":"v1.10.0-B2112002 (pre-release)","text":"<p>What's changed since pre-release v1.10.0-B2111024:</p> <ul> <li>Bug fixes:<ul> <li>Fixed module configuration is not loaded when case does not match. #864</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v1100-b2111024-pre-release","title":"v1.10.0-B2111024 (pre-release)","text":"<p>What's changed since v1.9.0:</p> <ul> <li>General improvements:<ul> <li>Added JSON support for reading rules and selectors from pipeline. #857</li> <li>Added <code>HasSchema</code> expression to check the schema of an object. #860<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.SourceLink.GitHub to 1.1.1. #856</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>$Assert.HasJsonSchema</code> accepts empty value. #859</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190","title":"v1.9.0","text":"<p>What's changed since v1.8.0:</p> <ul> <li>General improvements:<ul> <li>Added improvements to YAML output for <code>Get-PSRuleBaseline</code>. #829</li> <li>Added <code>-Initialize</code> convention block. #826<ul> <li>Use this block to perform any initialization that is required before any rules are run.</li> <li>This block is only run once instead of <code>-Begin</code> which is run once per object.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> <li>Allow lifetime services to be used. #827<ul> <li>Use <code>$PSRule.AddService</code> and <code>$PSRule.GetService</code> to add a service.</li> <li>Services allows a singleton instance to be used and shared across multiple rules.</li> <li>PSRule will automatically dispose the service when all rules have run.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> <li>Added <code>Export-PSRuleBaseline</code> cmdlet to export baseline. #622</li> <li>Added JSON output format for Baseline cmdlets. #839</li> <li>Allow downstream issues to be consumed. #843<ul> <li>Objects can be flagged with issues that have been generated externally.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Migrated default baseline to module configuration. #809<ul> <li>This enables configuration of the default baseline for a module with a module configuration.</li> <li>This depreciate configuring the default baseline within the module manifest.</li> <li>Modules using manifest configuration will start warning from v1.9.0.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added JSON support to read baselines from pipeline. #845</li> </ul> </li> <li>Engineering:<ul> <li>Bump System.Drawing.Common dependency to v6.0.0. #848</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed convention execution is out of order. #835</li> </ul> </li> </ul> <p>What's changed since pre-release v1.9.0-B2111024:</p> <ul> <li>Engineering:<ul> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v6.0.0. #851</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2111024-pre-release","title":"v1.9.0-B2111024 (pre-release)","text":"<p>What's changed since pre-release v1.9.0-B2111009:</p> <ul> <li>General improvements:<ul> <li>Allow downstream issues to be consumed. #843<ul> <li>Objects can be flagged with issues that have been generated externally.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Migrated default baseline to module configuration. #809<ul> <li>This enables configuration of the default baseline for a module with a module configuration.</li> <li>This depreciate configuring the default baseline within the module manifest.</li> <li>Modules using manifest configuration will start warning from v1.9.0.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added JSON support to read baselines from pipeline. #845</li> </ul> </li> <li>Engineering:<ul> <li>Bump System.Drawing.Common dependency to v6.0.0. #848</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2111009-pre-release","title":"v1.9.0-B2111009 (pre-release)","text":"<p>What's changed since pre-release v1.9.0-B2110027:</p> <ul> <li>General improvements:<ul> <li>Added JSON output format for Baseline cmdlets. #839</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed convention execution is out of order. #835</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2110027-pre-release","title":"v1.9.0-B2110027 (pre-release)","text":"<p>What's changed since pre-release v1.9.0-B2110015:</p> <ul> <li>General improvements:<ul> <li>Added <code>Export-PSRuleBaseline</code> cmdlet to export baseline. #622</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2110015-pre-release","title":"v1.9.0-B2110015 (pre-release)","text":"<p>What's changed since v1.8.0:</p> <ul> <li>General improvements:<ul> <li>Added improvements to YAML output for <code>Get-PSRuleBaseline</code>. #829</li> <li>Added <code>-Initialize</code> convention block. #826<ul> <li>Use this block to perform any initialization that is required before any rules are run.</li> <li>This block is only run once instead of <code>-Begin</code> which is run once per object.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> <li>Allow lifetime services to be used. #827<ul> <li>Use <code>$PSRule.AddService</code> and <code>$PSRule.GetService</code> to add a service.</li> <li>Services allows a singleton instance to be used and shared across multiple rules.</li> <li>PSRule will automatically dispose the service when all rules have run.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180","title":"v1.8.0","text":"<p>What's changed since v1.7.2:</p> <ul> <li>General improvements:<ul> <li>Added YAML output format support for <code>Get-PSRuleBaseline</code>. #326</li> <li>Added YAML/JSON output format support for <code>Get-PSRule</code>. #128</li> <li>Added <code>Output.JsonIndent</code> option for JSON output format. #817</li> <li>Added assertion helpers and expressions for improving intersection checks. #795<ul> <li>Added <code>Count</code> to determine of the field has a specific number of elements.</li> <li>Added <code>SetOf</code> to determine if a collection is another collection.</li> <li>Added <code>Subset</code> to determine if a collection is includes another collection.</li> <li>See about_PSRule_Assert and about_PSRule_Expressions for details.</li> </ul> </li> <li>Added support for conditional reason messages with <code>ReasonIf</code>. #804<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for <code>type</code> and <code>name</code> expression properties. #810<ul> <li>Use <code>type</code> to compare the bound type of the current object.</li> <li>Use <code>name</code> to compare the bound name of the current object.</li> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Migration of Pester v4 tests to Pester v5. #478</li> </ul> </li> </ul> <p>What's changed since pre-release v1.8.0-B2110030:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2110030-pre-release","title":"v1.8.0-B2110030 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2110020:</p> <ul> <li>General improvements:<ul> <li>Added <code>Output.JsonIndent</code> option for JSON output format. #817</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2110020-pre-release","title":"v1.8.0-B2110020 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2110006:</p> <ul> <li>General improvements:<ul> <li>Added YAML/JSON output format support for <code>Get-PSRule</code>. #128</li> </ul> </li> <li>Engineering:<ul> <li>Migration of Pester v4 tests to Pester v5. #478</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2110006-pre-release","title":"v1.8.0-B2110006 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2109022:</p> <ul> <li>General improvements:<ul> <li>Added YAML output format support for <code>Get-PSRuleBaseline</code>. #326</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2109022-pre-release","title":"v1.8.0-B2109022 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2109015:</p> <ul> <li>General improvements:<ul> <li>Added support for conditional reason messages with <code>ReasonIf</code>. #804<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for <code>type</code> and <code>name</code> expression properties. #810<ul> <li>Use <code>type</code> to compare the bound type of the current object.</li> <li>Use <code>name</code> to compare the bound name of the current object.</li> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2109015-pre-release","title":"v1.8.0-B2109015 (pre-release)","text":"<p>What's changed since v1.7.2:</p> <ul> <li>General improvements:<ul> <li>Added assertion helpers and expressions for improving intersection checks. #795<ul> <li>Added <code>Count</code> to determine of the field has a specific number of elements.</li> <li>Added <code>SetOf</code> to determine if a collection is another collection.</li> <li>Added <code>Subset</code> to determine if a collection is includes another collection.</li> <li>See about_PSRule_Assert and about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v172","title":"v1.7.2","text":"<p>What's changed since v1.7.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed <code>Get-PSRuleBaseline</code> does not return any results from module. #801</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v171","title":"v1.7.1","text":"<p>What's changed since v1.7.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed ResourceTags does not contain a method named ToHashtable. #798</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170","title":"v1.7.0","text":"<p>What's changed since v1.6.0:</p> <ul> <li>Engine features:<ul> <li>Added support for generating badges from rule results. #623<ul> <li>Standard or custom badges can be generated using a convention and the badge API.</li> <li>See about_PSRule_Badges for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Rule results now include a run ID or each run. #774<ul> <li>Run ID is returned in <code>Assert-PSRule</code> output at the end of each run by default.</li> <li>By default a unique <code>runId</code> is generated when the rule is run.</li> <li>The <code>Output.Footer</code>option was added to configure the output footer.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Automatically exclude common repository files from input files. #721<ul> <li>Added <code>Input.IgnoreRepositoryCommon</code> option to change default behavior.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added aggregation assertion methods for <code>AnyOf</code> and <code>AllOf</code>. #776<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Allow baselines to include local rules. #756<ul> <li>The <code>Rule.IncludeLocal</code>option was automatically include local/ standalone rules not in a module.</li> <li>This option is useful when you want to include local rules not included in a baseline.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed configuration array deserializes as dictionary from YAML options. #779</li> </ul> </li> </ul> <p>What's changed since pre-release v1.7.0-B2109002:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2109002-pre-release","title":"v1.7.0-B2109002 (pre-release)","text":"<p>What's changed since pre-release v1.7.0-B2108032:</p> <ul> <li>General improvements:<ul> <li>Allow baselines to include local rules. #756<ul> <li>The <code>Rule.IncludeLocal</code>option was automatically include local/ standalone rules not in a module.</li> <li>This option is useful when you want to include local rules not included in a baseline.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2108032-pre-release","title":"v1.7.0-B2108032 (pre-release)","text":"<p>What's changed since pre-release v1.7.0-B2108021:</p> <ul> <li>Engine features:<ul> <li>Added support for generating badges from rule results. #623<ul> <li>Standard or custom badges can be generated using a convention and the badge API.</li> <li>See about_PSRule_Badges for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Rule results now include a run ID or each run. #774<ul> <li>Run ID is returned in <code>Assert-PSRule</code> output at the end of each run by default.</li> <li>By default a unique <code>runId</code> is generated when the rule is run.</li> <li>The <code>Output.Footer</code>option was added to configure the output footer.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2108021-pre-release","title":"v1.7.0-B2108021 (pre-release)","text":"<p>What's changed since pre-release v1.7.0-B2108016:</p> <ul> <li>Bug fixes:<ul> <li>Fixed configuration array deserializes as dictionary from YAML options. #779</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2108016-pre-release","title":"v1.7.0-B2108016 (pre-release)","text":"<p>What's changed since v1.6.0:</p> <ul> <li>General improvements:<ul> <li>Automatically exclude common repository files from input files. #721<ul> <li>Added <code>Input.IgnoreRepositoryCommon</code> option to change default behavior.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added aggregation assertion methods for <code>AnyOf</code> and <code>AllOf</code>. #776<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v161","title":"v1.6.1","text":"<p>What's changed since v1.6.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed configuration array deserializes as dictionary from YAML options. #779</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v160","title":"v1.6.0","text":"<p>What's changed since v1.5.0:</p> <ul> <li>Engine features:<ul> <li>Added support for YAML rules. #603<ul> <li>YAML rules evaluate an expression tree and return a result for each object.</li> <li>YAML provides an additional option for defining rules in addition to PowerShell script rules.</li> <li>Type and selector pre-conditions are supported.</li> <li>See about_PSRule_Rules for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added support for object source location in validation. #757</li> <li>Default rule source location <code>.ps-rule/</code> is automatically included. #742<ul> <li>Added <code>Include.Path</code> and <code>Include.Module</code> options to automatically include rule sources.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed target binding across multiple scopes. #762</li> </ul> </li> </ul> <p>What's changed since pre-release v1.6.0-B2108009:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v160-b2108009-pre-release","title":"v1.6.0-B2108009 (pre-release)","text":"<p>What's changed since pre-release v1.6.0-B2108003:</p> <ul> <li>Engine features:<ul> <li>Added support for YAML rules. #603<ul> <li>YAML rules evaluate an expression tree and return a result for each object.</li> <li>YAML provides an additional option for defining rules in addition to PowerShell script rules.</li> <li>Type and selector pre-conditions are supported.</li> <li>See about_PSRule_Rules for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v160-b2108003-pre-release","title":"v1.6.0-B2108003 (pre-release)","text":"<p>What's changed since pre-release v1.6.0-B2107008:</p> <ul> <li>Bug fixes:<ul> <li>Fixed target binding across multiple scopes. #762</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v160-b2107008-pre-release","title":"v1.6.0-B2107008 (pre-release)","text":"<p>What's changed since v1.5.0:</p> <ul> <li>General improvements:<ul> <li>Added support for object source location in validation. #757</li> <li>Default rule source location <code>.ps-rule/</code> is automatically included. #742<ul> <li>Added <code>Include.Path</code> and <code>Include.Module</code> options to automatically include rule sources.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v150","title":"v1.5.0","text":"<p>What's changed since v1.4.0:</p> <ul> <li>General improvements:<ul> <li>Added string selector conditions. #747<ul> <li>Use <code>startWith</code>, <code>contains</code>, and <code>endsWith</code> to check for a sub-string.</li> <li>Use <code>isString</code>, <code>isLower</code>, and <code>isUpper</code> to check for string type and casing.</li> <li>See about_PSRule_Selectors for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.2.1. #740</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed options schema should allow spacing after <code>@pre</code>. #743</li> <li>Fixed match selector expression passing on missing field. #745</li> </ul> </li> </ul> <p>What's changed since pre-release v1.5.0-B2107009:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v150-b2107009-pre-release","title":"v1.5.0-B2107009 (pre-release)","text":"<p>What's changed since pre-release v1.5.0-B2106006:</p> <ul> <li>General improvements:<ul> <li>Added string selector conditions. #747<ul> <li>Use <code>startWith</code>, <code>contains</code>, and <code>endsWith</code> to check for a sub-string.</li> <li>Use <code>isString</code>, <code>isLower</code>, and <code>isUpper</code> to check for string type and casing.</li> <li>See about_PSRule_Selectors for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.2.1. #740</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed options schema should allow spacing after <code>@pre</code>. #743</li> <li>Fixed match selector expression passing on missing field. #745</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v150-b2106006-pre-release","title":"v1.5.0-B2106006 (pre-release)","text":"<p>What's changed since v1.4.0:</p> <ul> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.2.0. #736</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140","title":"v1.4.0","text":"<p>What's changed since v1.3.0:</p> <ul> <li>General improvements:<ul> <li>PSRule banner can be configured in output when using <code>Assert-PSRule</code>. #708</li> <li>Input source location of objects are included in results.<ul> <li>Input source location of objects from JSON and YAML input files are read automatically. #624</li> <li>Input source location of objects from the pipeline are read from properties. #729</li> </ul> </li> <li>Assert output improvements:<ul> <li>Added support for Visual Studio Code with <code>VisualStudioCode</code> style. #731<ul> <li>Updated output format provides support for problem matchers in task output.</li> </ul> </li> <li>Automatically detect output style from environment variables. #732<ul> <li>Assert-PSRule now defaults to <code>Detect</code> instead of <code>Client</code>.</li> </ul> </li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Improved support for version constraints by:<ul> <li>Constraints can include prerelease versions of other matching versions. #714</li> <li>Constraints support using a <code>@prerelease</code> or <code>@pre</code> to include prerelease versions. #717</li> <li>Constraint sets allow multiple constraints to be joined together. #715</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed prerelease constraint handling for prerelease versions. #712</li> <li>Fixed null reference in convention for nested exceptions. #725</li> </ul> </li> </ul> <p>What's changed since pre-release v1.4.0-B2105041:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105041-pre-release","title":"v1.4.0-B2105041 (pre-release)","text":"<p>What's changed since pre-release v1.4.0-B2105032:</p> <ul> <li>General improvements:<ul> <li>Source location of objects from the pipeline are read from properties. #729</li> <li>Assert output improvements:<ul> <li>Added support for Visual Studio Code with <code>VisualStudioCode</code> style. #731<ul> <li>Updated output format provides support for problem matchers in task output.</li> </ul> </li> <li>Automatically detect output style from environment variables. #732<ul> <li>Assert-PSRule now defaults to <code>Detect</code> instead of <code>Client</code>.</li> </ul> </li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105032-pre-release","title":"v1.4.0-B2105032 (pre-release)","text":"<p>What's changed since pre-release v1.4.0-B2105019:</p> <ul> <li>Bug fixes:<ul> <li>Fixed null reference in convention for nested exceptions. #725</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105019-pre-release","title":"v1.4.0-B2105019 (pre-release)","text":"<p>What's changed since pre-release v1.4.0-B2105004:</p> <ul> <li>General improvements:<ul> <li>Source location of objects are included in results.<ul> <li>Source location of objects from JSON and YAML input files are read automatically. #624</li> </ul> </li> <li>Improved support for version constraints by:<ul> <li>Constraints can include prerelease versions of other matching versions. #714</li> <li>Constraints support using a <code>@prerelease</code> or <code>@pre</code> to include prerelease versions. #717</li> <li>Constraint sets allow multiple constraints to be joined together. #715</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed prerelease constraint handling for prerelease versions. #712</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105004-pre-release","title":"v1.4.0-B2105004 (pre-release)","text":"<p>What's changed since v1.3.0:</p> <ul> <li>General improvements:<ul> <li>PSRule banner can be configured in output when using <code>Assert-PSRule</code>. #708</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130","title":"v1.3.0","text":"<p>What's changed since v1.2.0:</p> <ul> <li>Engine features:<ul> <li>Options can be configured with environment variables. #691<ul> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Exclude <code>.git</code> sub-directory by default for recursive scans. #697<ul> <li>Added <code>Input.IgnoreGitPath</code> option to configure inclusion of <code>.git</code> path.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added file path assertion helpers. #679<ul> <li>Added <code>WithinPath</code> to check the file path field is within a specified path.</li> <li>Added <code>NotWithinPath</code> to check the file path field is not within a specified path</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added DateTime type assertion helper. #680<ul> <li>Added <code>IsDateTime</code> to check of object field is <code>[DateTime]</code>.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improved numeric comparison assertion helpers to compare <code>[DateTime]</code> fields. #685<ul> <li><code>Less</code>, <code>LessOrEqual</code>, <code>Greater</code>, and <code>GreaterOrEqual</code> compare the number of days from the current time.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improved handling of field names for objects implementing <code>IList</code>, <code>IEnumerable</code>, and index properties. #692</li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.1.1. #690</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed expected DocumentEnd got SequenceEnd. #698</li> </ul> </li> </ul> <p>What's changed since pre-release v1.3.0-B2105004:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2105004-pre-release","title":"v1.3.0-B2105004 (pre-release)","text":"<p>What's changed since pre-release v1.3.0-B2104042:</p> <ul> <li>Engine features:<ul> <li>Options can be configured with environment variables. #691<ul> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Exclude <code>.git</code> sub-directory by default for recursive scans. #697<ul> <li>Added <code>Input.IgnoreGitPath</code> option to configure inclusion of <code>.git</code> path.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2104042-pre-release","title":"v1.3.0-B2104042 (pre-release)","text":"<p>What's changed since pre-release v1.3.0-B2104030:</p> <ul> <li>Bug fixes:<ul> <li>Fixed expected DocumentEnd got SequenceEnd. #698</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2104030-pre-release","title":"v1.3.0-B2104030 (pre-release)","text":"<p>What's changed since pre-release v1.3.0-B2104021:</p> <ul> <li>General improvements:<ul> <li>Improved handling of field names for objects implementing <code>IList</code>, <code>IEnumerable</code>, and index properties. #692</li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.1.1. #690</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2104021-pre-release","title":"v1.3.0-B2104021 (pre-release)","text":"<p>What's changed since v1.2.0:</p> <ul> <li>General improvements:<ul> <li>Added file path assertion helpers. #679<ul> <li>Added <code>WithinPath</code> to check the file path field is within a specified path.</li> <li>Added <code>NotWithinPath</code> to check the file path field is not within a specified path</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added DateTime type assertion helper. #680<ul> <li>Added <code>IsDateTime</code> to check of object field is <code>[DateTime]</code>.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improved numeric comparison assertion helpers to compare <code>[DateTime]</code> fields. #685<ul> <li><code>Less</code>, <code>LessOrEqual</code>, <code>Greater</code>, and <code>GreaterOrEqual</code> compare the number of days from the current time.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120","title":"v1.2.0","text":"<p>What's changed since v1.1.0:</p> <ul> <li>Engine features:<ul> <li>Added support for extensibility with conventions. #650<ul> <li>Conventions provide an extensibility point within PSRule to execute actions within the pipeline.</li> <li>A convention can expose <code>Begin</code>, <code>Process</code>, and <code>End</code> blocks.</li> <li>In additional to within rules <code>$PSRule.Data</code> can be accessed from <code>Begin</code> and <code>Process</code> blocks.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> <li>Added support for object expansion with conventions. #661<ul> <li>Use the <code>$PSRule.Import</code> method to import child source objects into the pipeline.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> <li>Added support for complex pre-conditions with selectors. #649<ul> <li>See about_PSRule_Selectors for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added support for preferring automatic binding over custom binding configurations. #670<ul> <li>Added the <code>Binding.PreferTargetInfo</code> option to prefer target info specified by the object.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added strong apiVersion to resource types. #647<ul> <li>Resource schemas now support an <code>apiVersion</code> field.</li> <li>The <code>apiVersion</code> field is optional but recommended.</li> <li>Resources without a <code>apiVersion</code> field will not be supported from PSRule v2.</li> <li>Added warning to flag baseline without <code>apiVersion</code> set.</li> </ul> </li> <li>Added support for detecting files headers from additional file extensions using <code>FileHeader</code>. #664<ul> <li>Added <code>.bicep</code>, <code>.csx</code>, <code>.jsx</code>, <code>.groovy</code>, <code>.java</code>, <code>.json</code>, <code>.jsonc</code>, <code>.scala</code>, <code>.rb</code>, <code>.bat</code>, <code>.cmd</code>.</li> <li>Added support for <code>Jenkinsfile</code> and <code>Dockerfile</code> without an extension.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for automatic type binding with files that do not have a file extension. #665</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed dependent rule execution is skipped for consequent input objects. #657</li> </ul> </li> </ul> <p>What's changed since pre-release v1.2.0-B2103043:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103043-pre-release","title":"v1.2.0-B2103043 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103031:</p> <ul> <li>Engine features:<ul> <li>Added support for complex pre-conditions with selectors. #649</li> </ul> </li> <li>General improvements:<ul> <li>Added support for preferring automatic binding over custom binding configurations. #670<ul> <li>Added the <code>Binding.PreferTargetInfo</code> option to prefer target info specified by the object.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added strong apiVersion to resource types. #647<ul> <li>Resource schemas now support an <code>apiVersion</code> field.</li> <li>The <code>apiVersion</code> field is optional but recommended.</li> <li>Resources without a <code>apiVersion</code> field will not be supported from PSRule v2.</li> <li>Added warning to flag baseline without <code>apiVersion</code> set.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103031-pre-release","title":"v1.2.0-B2103031 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103023:</p> <ul> <li>General improvements:<ul> <li>Added support for detecting files headers from additional file extensions. #664<ul> <li>Added <code>.bicep</code>, <code>.csx</code>, <code>.jsx</code>, <code>.groovy</code>, <code>.java</code>, <code>.json</code>, <code>.jsonc</code>, <code>.scala</code>, <code>.rb</code>, <code>.bat</code>, <code>.cmd</code>.</li> <li>Added support for <code>Jenkinsfile</code> and <code>Dockerfile</code> without an extension.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for automatic type binding with files that do not have a file extension. #665</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103023-pre-release","title":"v1.2.0-B2103023 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103016:</p> <ul> <li>Engine features:<ul> <li>Added support for object expansion with conventions. #661<ul> <li>Use the <code>$PSRule.Import</code> method to import child source objects into the pipeline.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103016-pre-release","title":"v1.2.0-B2103016 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103008:</p> <ul> <li>Bug fixes:<ul> <li>Fixed dependent rule execution is skipped for consequent input objects. #657</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103008-pre-release","title":"v1.2.0-B2103008 (pre-release)","text":"<p>What's changed since v1.1.0:</p> <ul> <li>Engine features:<ul> <li>Added support for extensibility with conventions. #650<ul> <li>Conventions provide an extensibility point within PSRule to execute actions within the pipeline.</li> <li>A convention can expose <code>Begin</code>, <code>Process</code>, and <code>End</code> blocks.</li> <li>In additional to within rules <code>$PSRule.Data</code> can be accessed from <code>Begin</code> and <code>Process</code> blocks.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v110","title":"v1.1.0","text":"<p>What's changed since v1.0.3:</p> <ul> <li>Engine features:<ul> <li>Added assertion helpers. #640<ul> <li>Added <code>NotHasField</code> to check object does not have any of the specified fields.</li> <li>Added <code>Null</code> to check field value is null.</li> <li>Added <code>NotNull</code> to check field value is not null.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added type assertion helpers. #635<ul> <li>Added <code>IsNumeric</code> to check field value is a numeric types.</li> <li>Added <code>IsInteger</code> to check field value is an integer types.</li> <li>Added <code>IsBoolean</code> to check field value is a boolean.</li> <li>Added <code>IsArray</code> to check field value is an array.</li> <li>Added <code>IsString</code> to check field value is a string.</li> <li>Added <code>TypeOf</code> to check field value is a specified type.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added content helpers. #637<ul> <li>Added <code>$PSRule.GetContentFirstOrDefault</code> to get content and return the first object.</li> <li>Added <code>$PSRule.GetContentField</code> to get the field from content objects.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Updated <code>HasJsonSchema</code> assertion helper. #636<ul> <li>The URI scheme can optionally be ignored for <code>http://</code> or <code>https://</code> URIs.</li> <li>The fragment <code>#</code> is ignored.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for <code>-Outcome</code> and <code>-As</code> to produce filtered output from <code>Assert-PSRule</code>. #643<ul> <li>Configure <code>Output.As</code> with <code>Summary</code> to produce summarized results per object.</li> <li>Configure <code>Output.Outcome</code> to limit output to <code>Fail</code> or <code>Error</code>.</li> <li>See Assert-PSRule for details.</li> </ul> </li> </ul> </li> </ul> <p>What's changed since pre-release v1.1.0-B2102029:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v110-b2102029-pre-release","title":"v1.1.0-B2102029 (pre-release)","text":"<p>What's changed since pre-release v1.1.0-B2102024:</p> <ul> <li>General improvements:<ul> <li>Added support for <code>-Outcome</code> and <code>-As</code> to produce filtered output from <code>Assert-PSRule</code>. #643<ul> <li>Configure <code>Output.As</code> with <code>Summary</code> to produce summarized results per object.</li> <li>Configure <code>Output.Outcome</code> to limit output to <code>Fail</code> or <code>Error</code>.</li> <li>See Assert-PSRule for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v110-b2102024-pre-release","title":"v1.1.0-B2102024 (pre-release)","text":"<p>What's changed since pre-release v1.1.0-B2102019:</p> <ul> <li>Engine features:<ul> <li>Added assertion helpers. #640<ul> <li>Added <code>NotHasField</code> to check object does not have any of the specified fields.</li> <li>Added <code>Null</code> to check field value is null.</li> <li>Added <code>NotNull</code> to check field value is not null.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v110-b2102019-pre-release","title":"v1.1.0-B2102019 (pre-release)","text":"<p>What's changed since v1.0.3:</p> <ul> <li>Engine features:<ul> <li>Added type assertion helpers. #635<ul> <li>Added <code>IsNumeric</code> to check field value is a numeric types.</li> <li>Added <code>IsInteger</code> to check field value is an integer types.</li> <li>Added <code>IsBoolean</code> to check field value is a boolean.</li> <li>Added <code>IsArray</code> to check field value is an array.</li> <li>Added <code>IsString</code> to check field value is a string.</li> <li>Added <code>TypeOf</code> to check field value is a specified type.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added content helpers. #637<ul> <li>Added <code>$PSRule.GetContentFirstOrDefault</code> to get content and return the first object.</li> <li>Added <code>$PSRule.GetContentField</code> to get the field from content objects.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Updated <code>HasJsonSchema</code> assertion helper. #636<ul> <li>The URI scheme can optionally be ignored for <code>http://</code> or <code>https://</code> URIs.</li> <li>The fragment <code>#</code> is ignored.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v103","title":"v1.0.3","text":"<p>What's changed since v1.0.2:</p> <ul> <li>Bug fixes:<ul> <li>Fixed reason reported fields for <code>HasField</code> and <code>HasFields</code> assertion helpers. #632</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v102","title":"v1.0.2","text":"<p>What's changed since v1.0.1:</p> <ul> <li>Engineering:<ul> <li>Bump Manatee.Json dependency to 13.0.5. #619</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>GetContent</code> processing of <code>InputFileInfo</code>. #625</li> <li>Fixed null reference of rule reason with wide output. #626</li> <li>Fixed markdown help handling of inline code blocks with <code>[</code>. #627</li> <li>Fixed markdown help inclusion of fenced code blocks in notes and description. #628</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v101","title":"v1.0.1","text":"<p>What's changed since v1.0.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed module source key has already been added. #608</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v100","title":"v1.0.0","text":"<p>What's changed since v0.22.0:</p> <ul> <li>General improvements:<ul> <li>Added rule help link in failed <code>Assert-PSRule</code> output. #595</li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removed deprecated <code>$Rule</code> properties. #495</li> <li>Bump Manatee.Json dependency to 13.0.4. #591</li> </ul> </li> </ul> <p>What's changed since pre-release v1.0.0-B2011028:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v100-b2011028-pre-release","title":"v1.0.0-B2011028 (pre-release)","text":"<p>What's changed since v0.22.0:</p> <ul> <li>General improvements:<ul> <li>Added rule help link in failed <code>Assert-PSRule</code> output. #595</li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removed deprecated <code>$Rule</code> properties. #495</li> <li>Bump Manatee.Json dependency to 13.0.4. #591</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Important notes:</p> <ul> <li>Several options have been renamed and the old names will be removed in v3.   See deprecations for details.</li> <li> <p>Several properties of rule and language block elements will be removed from v3.   See deprecations for details.</p> </li> </ul> <p>Experimental features:</p> <ul> <li>Baseline groups allow you to use a friendly name to reference baselines.   See baselines for more information.</li> <li>Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition.   See functions for more information.</li> <li>Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties.   See sub-selectors for more information.</li> <li> <p>Processing of changes files only within a pipeline.   See creating your pipeline for more information.</p> </li> </ul> <p>Attention</p> <p>We are currently working towards the next release of PSRule. For more information see v3 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.</p>"},{"location":"CHANGELOG-v2/#v290","title":"v2.9.0","text":"<p>What's changed since release v2.8.1:</p> <ul> <li>New features:<ul> <li>Added sub-selector quantifiers for <code>allOf</code> or <code>anyOf</code> operators by @BernieWhite.   #1423<ul> <li>Quantifiers allow you to specify the number of matches with <code>count</code>, <code>less</code>, <code>lessOrEqual</code>, <code>greater</code>, or <code>greaterOrEqual</code>.</li> <li>See Sub-selectors for more information.</li> </ul> </li> <li>Added support for new functions by @BernieWhite.   #1422<ul> <li>Added support for <code>padLeft</code>, and <code>padRight</code>.</li> </ul> </li> <li>Experimental: Added support for baseline groups by @BernieWhite.   #1541<ul> <li>Baseline groups allow you to reference a baseline by a friendly name.</li> <li>Update the baseline group to point to a new baseline.</li> <li>Currently only a single baseline can be referenced by a baseline group.</li> <li>See baselines for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added style and improved handling for restore command by @BernieWhite.   #1152</li> <li>Important change: Rename of execution options by @BernieWhite.   #1456<ul> <li>Renamed options allow configuration of output level as <code>Ignore</code>, <code>Warn</code>, <code>Error</code>, or <code>Debug</code>.</li> <li><code>Execution.AliasReferenceWarning</code> is replaced with <code>Execution.AliasReference</code>.</li> <li><code>Execution.InconclusiveWarning</code> is replaced with <code>Execution.RuleInconclusive</code>.</li> <li><code>Execution.InvariantCultureWarning</code> is replaced with <code>Execution.InvariantCulture</code>.</li> <li><code>Execution.NotProcessedWarning</code> is replaced with <code>Execution.UnprocessedObject</code>.</li> <li>Deprecated <code>AliasReferenceWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InconclusiveWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InvariantCultureWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>NotProcessedWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Improved schema display names by @BernieWhite.   #1488</li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.1.   #1510</li> <li>Bump Microsoft.NET.Test.Sdk to v17.6.2.   #1544</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.6.0.   #1534</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed tool output on access denied to path by @BernieWhite.   #1490</li> <li>Fixed tool exit code on error or failure by @BernieWhite.   #1491</li> <li>Fixed include local not automatically being enabled for default module baseline by @BernieWhite.   #1506</li> </ul> </li> </ul> <p>What's changed since pre-release v2.9.0-B0068:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v290-b0068-pre-release","title":"v2.9.0-B0068 (pre-release)","text":"<p>What's changed since pre-release v2.9.0-B0033:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for baseline groups by @BernieWhite.   #1541<ul> <li>Baseline groups allow you to reference a baseline by a friendly name.</li> <li>Update the baseline group to point to a new baseline.</li> <li>Currently only a single baseline can be referenced by a baseline group.</li> <li>See baselines for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added style and improved handling for restore command by @BernieWhite.   #1152</li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.6.2.   #1544</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.6.0.   #1534</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed include local not automatically being enabled for default module baseline by @BernieWhite.   #1506</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v290-b0033-pre-release","title":"v2.9.0-B0033 (pre-release)","text":"<p>What's changed since pre-release v2.9.0-B0013:</p> <ul> <li>New features:<ul> <li>Added sub-selector quantifiers for <code>allOf</code> or <code>anyOf</code> operators by @BernieWhite.   #1423<ul> <li>Quantifiers allow you to specify the number of matches with <code>count</code>, <code>less</code>, <code>lessOrEqual</code>, <code>greater</code>, or <code>greaterOrEqual</code>.</li> <li>See Sub-selectors for more information.</li> </ul> </li> <li>Added support for new functions by @BernieWhite.   #1422<ul> <li>Added support for <code>padLeft</code>, and <code>padRight</code>.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v290-b0013-pre-release","title":"v2.9.0-B0013 (pre-release)","text":"<p>What's changed since release v2.8.1:</p> <ul> <li>General improvements:<ul> <li>Important change: Rename of execution options by @BernieWhite.   #1456<ul> <li>Renamed options allow configuration of output level as <code>Ignore</code>, <code>Warn</code>, <code>Error</code>, or <code>Debug</code>.</li> <li><code>Execution.AliasReferenceWarning</code> is replaced with <code>Execution.AliasReference</code>.</li> <li><code>Execution.InconclusiveWarning</code> is replaced with <code>Execution.RuleInconclusive</code>.</li> <li><code>Execution.InvariantCultureWarning</code> is replaced with <code>Execution.InvariantCulture</code>.</li> <li><code>Execution.NotProcessedWarning</code> is replaced with <code>Execution.UnprocessedObject</code>.</li> <li>Deprecated <code>AliasReferenceWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InconclusiveWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InvariantCultureWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>NotProcessedWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Improved schema display names by @BernieWhite.   #1488</li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.1.   #1510</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.5.0.   #1455</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed tool output on access denied to path by @BernieWhite.   #1490</li> <li>Fixed tool exit code on error or failure by @BernieWhite.   #1491</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v281","title":"v2.8.1","text":"<p>What's changed since release v2.8.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed wrong message for excluded rules by @BernieWhite.   #1493</li> <li>Fixed job summary reports completed time by @BernieWhite.   #1492</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280","title":"v2.8.0","text":"<p>What's changed since release v2.7.0:</p> <ul> <li>General improvements:<ul> <li>Important change: Replaced <code>SuppressedRuleWarning</code> execution option with <code>RuleSuppressed</code> by @BernieWhite.   #1456<ul> <li>Improved options for output of suppressed rules with <code>RuleSuppressed</code> option.</li> <li>Deprecated <code>SuppressedRuleWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Added support for logging excluded rules by @BernieWhite.   #1432<ul> <li>Configure <code>Execution.RuleExcluded</code> to control output level of excluded rules as <code>Ignore</code>, <code>Warn</code>, <code>Error</code>, or <code>Debug</code>.</li> </ul> </li> <li>Added additional options to schema for PSRule for Azure by @BernieWhite.   #1446</li> <li>Improved error message for failing to read options file by @BernieWhite.   #1433</li> <li>Added support for import within initialize block by @BernieWhite.   #1448</li> <li>Added support for direct typing on import by @BernieWhite.   #1449<ul> <li>Use the <code>$PSRule.ImportWithType</code> method to import an object with a specific type.</li> </ul> </li> <li>Added support for case sensitivity matching with <code>match</code> and <code>notMatch</code> expressions by @BernieWhite.   #1480</li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.0.   #1414   Bump Microsoft.CodeAnalysis.Common to v4.4.0.   #1341</li> <li>Bump BenchmarkDotNet to v0.13.5.   #1413</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5.   #1413</li> <li>Bump Microsoft.NET.Test.Sdk to v17.5.0.   #1442</li> <li>Bump Newtonsoft.Json to v13.0.3.   #1467</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1.   #1468</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite.   #1405</li> <li>Fixed no output with using job summary with as summary by @BernieWhite.   #1483<ul> <li>Fixed output and added error for unsupported scenarios.</li> </ul> </li> <li>Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite.   #1083</li> <li>Fixed LocalizedData is not exposed to conventions by @BernieWhite.   #1477</li> <li>Fixed problem binding when not set locally by @BernieWhite.   #1473</li> </ul> </li> </ul> <p>What's changed since pre-release v2.8.0-B0171:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0171-pre-release","title":"v2.8.0-B0171 (pre-release)","text":"<p>What's changed since pre-release v2.8.0-B0121:</p> <ul> <li>General improvements:<ul> <li>Added support for case sensitivity matching with <code>match</code> and <code>notMatch</code> expressions by @BernieWhite.   #1480</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed no output with using job summary with as summary by @BernieWhite.   #1483<ul> <li>Fixed output and added error for unsupported scenarios.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0121-pre-release","title":"v2.8.0-B0121 (pre-release)","text":"<p>What's changed since pre-release v2.8.0-B0076:</p> <ul> <li>Bug fixes:<ul> <li>Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite.   #1083</li> <li>Fixed LocalizedData is not exposed to conventions by @BernieWhite.   #1477</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0076-pre-release","title":"v2.8.0-B0076 (pre-release)","text":"<p>What's changed since pre-release v2.8.0-B0034:</p> <ul> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to v13.0.3.   #1467</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1.   #1468</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed problem binding when not set locally by @BernieWhite.   #1473</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0034-pre-release","title":"v2.8.0-B0034 (pre-release)","text":"<p>What's changed since v2.7.0:</p> <ul> <li>General improvements:<ul> <li>Important change: Replaced <code>SuppressedRuleWarning</code> execution option with <code>RuleSuppressed</code> by @BernieWhite.   #1456<ul> <li>Improved options for output of suppressed rules with <code>RuleSuppressed</code> option.</li> <li>Deprecated <code>SuppressedRuleWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Added support for logging excluded rules by @BernieWhite.   #1432</li> <li>Added additional options to schema for PSRule for Azure by @BernieWhite.   #1446</li> <li>Improved error message for failing to read options file by @BernieWhite.   #1433</li> <li>Added support for import within initialize block by @BernieWhite.   #1448</li> <li>Added support for direct typing on import by @BernieWhite.   #1449<ul> <li>Use the <code>$PSRule.ImportWithType</code> method to import an object with a specific type.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.0.   #1414</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.0.   #1374   Bump Microsoft.CodeAnalysis.Common to v4.4.0.   #1341</li> <li>Bump BenchmarkDotNet to v0.13.5.   #1413</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5.   #1413</li> <li>Bump Microsoft.NET.Test.Sdk to v17.5.0.   #1442</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite.   #1405</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270","title":"v2.7.0","text":"<p>What's changed since v2.6.0:</p> <ul> <li>New features:<ul> <li>Added API version date comparison assertion method and expression by @BernieWhite.   #1356</li> <li>Added support for new functions by @BernieWhite.   #1227<ul> <li>Added support for <code>trim</code>, <code>replace</code>, <code>split</code>, <code>first</code>, and <code>last</code>.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added support target scope by @BernieWhite.   #1350</li> <li>Added support for <code>hasValue</code> expression with <code>scope</code> by @BernieWhite.   #1382</li> <li>Return target object scope as an array by @BernieWhite.   #1383</li> <li>Improve support of string comparisons to support an array of strings by @BernieWhite.   #1384</li> <li>Added help properties to rules from YAML/ JSON resources by @BernieWhite.   #1386</li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to v13.0.2.   #1358</li> <li>Bump System.Drawing.Common to v7.0.0.   #1332</li> <li>Bump Microsoft.NET.Test.Sdk to v17.4.1.   #1389</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed exception with comments in JSON baselines by @BernieWhite.   #1336</li> <li>Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite.   #1348</li> <li>Fixed exception calling <code>RuleSource</code> value cannot be null by @BernieWhite.   #1343</li> <li>Fixed null reference for link property by @BernieWhite.   #1393</li> <li>Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite.   #1394</li> <li>Fixed CLI failed to load required assemblies by @BernieWhite.   #1361</li> <li>Fixed CLI ignores modules specified in <code>Include.Modules</code> by @BernieWhite.   #1362</li> <li>Fixed job summary directory creation by @BernieWhite.   #1353</li> <li>Fixed same key for ref and name by @BernieWhite #1354</li> <li>Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite.   #1376</li> <li>Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite.   #1378</li> <li>Fixed loop stuck parsing JSON <code>allOf</code> <code>not</code> rule condition by @BernieWhite.   #1370</li> <li>Fixed handling of uint64 with <code>LessOrEqual</code> assertion method by @BernieWhite.   #1366</li> </ul> </li> </ul> <p>What's changed since pre-release v2.7.0-B0126:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0126-pre-release","title":"v2.7.0-B0126 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0097:</p> <ul> <li>Bug fixes:<ul> <li>Fixed null reference for link property by @BernieWhite.   #1393</li> <li>Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite.   #1394</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0097-pre-release","title":"v2.7.0-B0097 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0070:</p> <ul> <li>General improvements:<ul> <li>Added support for <code>hasValue</code> expression with <code>scope</code> by @BernieWhite.   #1382</li> <li>Return target object scope as an array by @BernieWhite.   #1383</li> <li>Improve support of string comparisons to support an array of strings by @BernieWhite.   #1384</li> <li>Added help properties to rules from YAML/ JSON resources by @BernieWhite.   #1386</li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to v13.0.2.   #1358</li> <li>Bump System.Drawing.Common to v7.0.0.   #1332</li> <li>Bump Microsoft.NET.Test.Sdk to v17.4.1.   #1389</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0070-pre-release","title":"v2.7.0-B0070 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0049:</p> <ul> <li>Bug fixes:<ul> <li>Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite.   #1376</li> <li>Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite.   #1378</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0049-pre-release","title":"v2.7.0-B0049 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0031:</p> <ul> <li>Bug fixes:<ul> <li>Fixed loop stuck parsing JSON <code>allOf</code> <code>not</code> rule condition by @BernieWhite.   #1370</li> <li>Fixed handling of uint64 with <code>LessOrEqual</code> assertion method by @BernieWhite.   #1366</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0031-pre-release","title":"v2.7.0-B0031 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0016:</p> <ul> <li>New features:<ul> <li>Added API version date comparison assertion method and expression by @BernieWhite.   #1356</li> <li>Added support for new functions by @BernieWhite.   #1227<ul> <li>Added support for <code>trim</code>, <code>replace</code>, <code>split</code>, <code>first</code>, and <code>last</code>.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed CLI failed to load required assemblies by @BernieWhite.   #1361</li> <li>Fixed CLI ignores modules specified in <code>Include.Modules</code> by @BernieWhite.   #1362</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0016-pre-release","title":"v2.7.0-B0016 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0006:</p> <ul> <li>Bug fixes:<ul> <li>Fixed job summary directory creation by @BernieWhite.   #1353</li> <li>Fixed same key for ref and name by @BernieWhite #1354</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0006-pre-release","title":"v2.7.0-B0006 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0001:</p> <ul> <li>General improvements:<ul> <li>Added support target scope by @BernieWhite.   #1350</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed exception with comments in JSON baselines by @BernieWhite.   #1336</li> <li>Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite.   #1348</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0001-pre-release","title":"v2.7.0-B0001 (pre-release)","text":"<p>What's changed since v2.6.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed exception calling <code>RuleSource</code> value cannot be null by @BernieWhite.   #1343</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v260","title":"v2.6.0","text":"<p>What's changed since v2.5.3:</p> <ul> <li>New features:<ul> <li>Added support for generating job summaries by @BernieWhite.   #1264<ul> <li>Job summaries provide a markdown output for pipelines in addition to other supported output formats.</li> <li>To use, configure the <code>Output.JobSummaryPath</code> option.</li> </ul> </li> <li>Added support for time bound suppression groups by @BernieWhite.   #1335<ul> <li>Suppression groups can be configured to expire after a specified time by setting the <code>spec.expiresOn</code> property.</li> <li>When a suppression group expires, the suppression group will generate a warning by default.</li> <li>Configure the <code>Execution.SuppressionGroupExpired</code> option to ignore or error on expired suppression groups.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.4.0.   #1331</li> <li>Bump PSScriptAnalyzer to v1.21.0.   #1318</li> <li>Class clean up and documentation by @BernieWhite.   #1186</li> </ul> </li> </ul> <p>What's changed since pre-release v2.6.0-B0034:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v260-b0034-pre-release","title":"v2.6.0-B0034 (pre-release)","text":"<p>What's changed since pre-release v2.6.0-B0013:</p> <ul> <li>New features:<ul> <li>Added support for generating job summaries by @BernieWhite.   #1264<ul> <li>Job summaries provide a markdown output for pipelines in addition to other supported output formats.</li> <li>To use, configure the <code>Output.JobSummaryPath</code> option.</li> </ul> </li> <li>Added support for time bound suppression groups by @BernieWhite.   #1335<ul> <li>Suppression groups can be configured to expire after a specified time by setting the <code>spec.expiresOn</code> property.</li> <li>When a suppression group expires, the suppression group will generate a warning by default.</li> <li>Configure the <code>Execution.SuppressionGroupExpired</code> option to ignore or error on expired suppression groups.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.4.0.   #1331</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v260-b0013-pre-release","title":"v2.6.0-B0013 (pre-release)","text":"<p>What's changed since v2.5.3:</p> <ul> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.3.2.   #1283</li> <li>Bump PSScriptAnalyzer to v1.21.0.   #1318</li> <li>Class clean up and documentation by @BernieWhite.   #1186</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v253","title":"v2.5.3","text":"<p>What's changed since v2.5.2:</p> <ul> <li>Bug fixes:<ul> <li>Fixed incorrect XML header for encoding by @BernieWhite.   #1322</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v252","title":"v2.5.2","text":"<p>What's changed since v2.5.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed NUnit output does not escape characters in all result properties by @BernieWhite.   #1316</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v251","title":"v2.5.1","text":"<p>What's changed since v2.5.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed <code>In</code> with array source object and dot object path by @BernieWhite.   #1314</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250","title":"v2.5.0","text":"<p>What's changed since v2.4.2:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for only processing changed files by @BernieWhite.   #688<ul> <li>To ignore unchanged files, set the <code>Input.IgnoreUnchangedPath</code> option to <code>true</code>.</li> <li>See creating your pipeline for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added labels metadata from grouping and filtering rules by @BernieWhite.   #1272<ul> <li>Labels are metadata that extends on tags to provide a more structured way to group rules.</li> <li>Rules can be classified by setting the <code>metadata.labels</code> property or <code>-Labels</code> parameter.</li> </ul> </li> <li>Provide unblock for command line tools by @BernieWhite.   #1261</li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.3.1.   #1248</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite.   #1249<ul> <li>To use minimal initial session state set <code>Execution.InitialSessionState</code> to <code>Minimal</code>.</li> </ul> </li> <li>Fixed unhandled exception with GetRootedPath by @BernieWhite.   #1251</li> <li>Fixed Dockerfile case sensitivity by @BernieWhite.   #1269</li> </ul> </li> </ul> <p>What's changed since pre-release v2.5.0-B0080:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0080-pre-release","title":"v2.5.0-B0080 (pre-release)","text":"<p>What's changed since pre-release v2.5.0-B0045:</p> <ul> <li>Bug fixes:<ul> <li>Fixed exception with <code>PathExpressionBuilder.GetAllRecurse</code> by @BernieWhite.   #1301</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0045-pre-release","title":"v2.5.0-B0045 (pre-release)","text":"<p>What's changed since pre-release v2.5.0-B0015:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for only processing changed files by @BernieWhite.   #688<ul> <li>To ignore unchanged files, set the <code>Input.IgnoreUnchangedPath</code> option to <code>true</code>.</li> <li>See creating your pipeline for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added labels metadata from grouping and filtering rules by @BernieWhite.   #1272<ul> <li>Labels are metadata that extends on tags to provide a more structured way to group rules.</li> <li>Rules can be classified by setting the <code>metadata.labels</code> property or <code>-Labels</code> parameter.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed Dockerfile case sensitivity by @BernieWhite.   #1269</li> <li>Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz.   #1286 #1285</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0015-pre-release","title":"v2.5.0-B0015 (pre-release)","text":"<p>What's changed since pre-release v2.5.0-B0004:</p> <ul> <li>General improvements:<ul> <li>Provide unblock for command line tools by @BernieWhite.   #1261</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0004-pre-release","title":"v2.5.0-B0004 (pre-release)","text":"<p>What's changed since v2.4.0:</p> <ul> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.3.1.   #1248</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite.   #1249<ul> <li>To use minimal initial session state set <code>Execution.InitialSessionState</code> to <code>Minimal</code>.</li> </ul> </li> <li>Fixed unhandled exception with GetRootedPath by @BernieWhite.   #1251</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v242","title":"v2.4.2","text":"<p>What's changed since v2.4.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed exception with <code>PathExpressionBuilder.GetAllRecurse</code> by @BernieWhite.   #1301</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v241","title":"v2.4.1","text":"<p>What's changed since v2.4.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz.   #1286 #1285</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240","title":"v2.4.0","text":"<p>What's changed since v2.3.2:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite.   #1227 #1016<ul> <li>Added conversion functions <code>boolean</code>, <code>string</code>, and <code>integer</code>.</li> <li>Added lookup functions <code>configuration</code>, and <code>path</code>.</li> <li>Added string functions <code>concat</code>, <code>substring</code>.</li> <li>See functions for more information.</li> </ul> </li> <li>Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite.   #1024 #1045<ul> <li>Sub-selector pre-conditions add an additional expression to determine if a rule is executed.</li> <li>Sub-selector object filters provide an way to filter items from list properties.</li> <li>See sub-selectors for more information.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Improvements to PSRule engine API documentation by @BernieWhite.   #1186</li> <li>Updates to PSRule engine API by @BernieWhite.   #1152<ul> <li>Added tool support for baselines parameter.</li> <li>Added module path discovery.</li> <li>Added output for verbose and debug messages.</li> </ul> </li> <li>Bump support projects to .NET 6 by @BernieWhite.   #1209</li> <li>Bump Microsoft.NET.Test.Sdk to v17.3.0.   #1213</li> <li>Bump BenchmarkDotNet to v0.13.2.   #1241</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2.   #1242</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite.   #1229<ul> <li>Added <code>Execution.DuplicateResourceId</code> option to configure PSRule behaviour.</li> <li>By default, duplicate resource identifiers return an error.</li> </ul> </li> <li>Fixed exception on JSON baseline without a synopsis by @BernieWhite.   #1230</li> <li>Fixed repository information not in output by @BernieWhite.   #1219</li> </ul> </li> </ul> <p>What's changed since pre-release v2.4.0-B0091:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0091-pre-release","title":"v2.4.0-B0091 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0063:</p> <ul> <li>Engineering:<ul> <li>Bump BenchmarkDotNet to v0.13.2.   #1241</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2.   #1242</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0063-pre-release","title":"v2.4.0-B0063 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0039:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite.   #1024 #1045<ul> <li>Sub-selector pre-conditions add an additional expression to determine if a rule is executed.</li> <li>Sub-selector object filters provide an way to filter items from list properties.</li> <li>See sub-selectors for more information.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Improvements to PSRule engine API documentation by @BernieWhite.   #1186</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0039-pre-release","title":"v2.4.0-B0039 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0022:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite.   #1227 #1016<ul> <li>Added conversion functions <code>boolean</code>, <code>string</code>, and <code>integer</code>.</li> <li>Added lookup functions <code>configuration</code>, and <code>path</code>.</li> <li>Added string functions <code>concat</code>, <code>substring</code>.</li> <li>See functions for more information.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite.   #1229<ul> <li>Added <code>Execution.DuplicateResourceId</code> option to configure PSRule behaviour.</li> <li>By default, duplicate resource identifiers return an error.</li> </ul> </li> <li>Fixed exception on JSON baseline without a synopsis by @BernieWhite.   #1230</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0022-pre-release","title":"v2.4.0-B0022 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0009:</p> <ul> <li>Engineering:<ul> <li>Updates to PSRule engine API by @BernieWhite.   #1152<ul> <li>Added tool support for baselines parameter.</li> <li>Added module path discovery.</li> <li>Added output for verbose and debug messages.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0009-pre-release","title":"v2.4.0-B0009 (pre-release)","text":"<p>What's changed since v2.3.2:</p> <ul> <li>Engineering:<ul> <li>Bump support projects to .NET 6 by @BernieWhite.   #1209</li> <li>Bump Microsoft.NET.Test.Sdk to v17.3.0.   #1213</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed repository information not in output by @BernieWhite.   #1219</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v232","title":"v2.3.2","text":"<p>What's changed since v2.3.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixes lost scope for rules by @BernieWhite.   #1214</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v231","title":"v2.3.1","text":"<p>What's changed since v2.3.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed object path join handling of self path identifier by @BernieWhite.   #1204</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230","title":"v2.3.0","text":"<p>What's changed since v2.2.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>PathPrefix</code> method to add an object path prefix to assertion reasons by @BernieWhite.   #1198</li> <li>Added support for binding with JSON objects by @BernieWhite.   #1182</li> <li>Added support for full path from JSON objects by @BernieWhite.   #1174</li> <li>Improved reporting of full object path from pre-processed results by @BernieWhite.   #1169</li> <li>Added PSRule for Azure expansion configuration to options schema by @BernieWhite.   #1149</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit to v2.4.2.   #1200</li> <li>Expose online link extension method by @BernieWhite.   #1195</li> <li>Added comment documentation to .NET classes and interfaces by @BernieWhite.   #1186</li> <li>Added publishing support for NuGet symbol packages @BernieWhite.   #1173</li> <li>Updated outcome option docs by @BernieWhite.   #1166</li> <li>Bump Sarif.Sdk to v2.4.16.   #1177</li> <li>Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite.   #1152</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes JSON parsing of string array for single objects by @BernieWhite.   #1193</li> <li>Fixed handling for JSON objects in rules by @BernieWhite.   #1187</li> <li>Fixed null object reference for object equity comparison by @BernieWhite.   #1157</li> <li>Fixed expression evaluation not logging debug output when using the <code>-Debug</code> switch by @BernieWhite.   #1158</li> <li>Fixed startIndex cannot be larger than length of string by @BernieWhite.   #1160</li> <li>Fixed path within SDK package causes <code>psd1</code> to compile by @BernieWhite.   #1146</li> </ul> </li> </ul> <p>What's changed since pre-release v2.3.0-B0163:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0163-pre-release","title":"v2.3.0-B0163 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0130:</p> <ul> <li>General improvements:<ul> <li>Added <code>PathPrefix</code> method to add an object path prefix to assertion reasons by @BernieWhite.   #1198</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit to v2.4.2.   #1200</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0130-pre-release","title":"v2.3.0-B0130 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0100:</p> <ul> <li>Engineering:<ul> <li>Expose online link extension method by @BernieWhite.   #1195</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes JSON parsing of string array for single objects by @BernieWhite.   #1193</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0100-pre-release","title":"v2.3.0-B0100 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0074:</p> <ul> <li>Engineering:<ul> <li>Added comment documentation to .NET classes and interfaces by @BernieWhite.   #1186</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling for JSON objects in rules by @BernieWhite.   #1187</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0074-pre-release","title":"v2.3.0-B0074 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0051:</p> <ul> <li>General improvements:<ul> <li>Added support for binding with JSON objects by @BernieWhite.   #1182</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0051-pre-release","title":"v2.3.0-B0051 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0030:</p> <ul> <li>General improvements:<ul> <li>Added support for full path from JSON objects by @BernieWhite.   #1174</li> </ul> </li> <li>Engineering:<ul> <li>Added publishing support for NuGet symbol packages @BernieWhite.   #1173</li> <li>Updated outcome option docs by @BernieWhite.   #1166</li> <li>Bump Sarif.Sdk to v2.4.16.   #1177</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0030-pre-release","title":"v2.3.0-B0030 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0015:</p> <ul> <li>General improvements:<ul> <li>Improved reporting of full object path from pre-processed results by @BernieWhite.   #1169</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0015-pre-release","title":"v2.3.0-B0015 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0006:</p> <ul> <li>Bug fixes:<ul> <li>Fixed null object reference for object equity comparison by @BernieWhite.   #1157</li> <li>Fixed expression evaluation not logging debug output when using the <code>-Debug</code> switch by @BernieWhite.   #1158</li> <li>Fixed startIndex cannot be larger than length of string by @BernieWhite.   #1160</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0006-pre-release","title":"v2.3.0-B0006 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0001:</p> <ul> <li>General improvements:<ul> <li>Added PSRule for Azure expansion configuration to options schema by @BernieWhite.   #1149</li> </ul> </li> <li>Engineering:<ul> <li>Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite.   #1152</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0001-pre-release","title":"v2.3.0-B0001 (pre-release)","text":"<p>What's changed since v2.2.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed path within SDK package causes <code>psd1</code> to compile by @BernieWhite.   #1146</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220","title":"v2.2.0","text":"<p>What's changed since v2.1.0:</p> <ul> <li>New features:<ul> <li>Added <code>notCount</code> expression and assertion helper by @ArmaanMcleod.   #1091</li> </ul> </li> <li>General improvements:<ul> <li>Improved reporting of the object path that caused rule failures by @BernieWhite.   #1092<ul> <li>Output include a new <code>Detail</code> property with details of the reason and the object path.</li> <li>Custom methods <code>ReasonFrom</code> and <code>ReasonIf</code> accept a <code>path</code> parameter to specify the object path.</li> </ul> </li> <li>Added informational message when output has been written to disk by @BernieWhite.   #1074<ul> <li>The <code>Output.Footer</code> option now supports <code>OutputFile</code> which reports the output file path.   This is enabled by default.</li> </ul> </li> <li>Added descendant selector to object path syntax by @BernieWhite.   #1133<ul> <li>Use <code>..</code> to traverse into child objects, for example <code>$..name</code> finds names for all nested objects.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to 13.0.1.   #1137</li> <li>Added more object path tests by @ArmaanMcleod.   #1110</li> <li>Bump xunit.runner.visualstudio to 2.4.5.   #1084</li> <li>Bump Pester to 5.3.3.   #1079</li> <li>Bump Microsoft.NET.Test.Sdk to 17.2.0.   #1089</li> <li>Added NuGet packaging publishing by @BernieWhite.   #1093</li> <li>Updated NuGet packaging metadata by @BernieWhite.   #1093</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed output of reason with wide format by @BernieWhite.   #1117</li> <li>Fixed piped input does not respect excluded paths by @BernieWhite.   #1114<ul> <li>By default, objects are not excluded by source.</li> <li>To exclude piped input based on source configure the <code>Input.IgnoreObjectSource</code> option.</li> </ul> </li> <li>Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite.   #1140</li> <li>Fixed grouping of logical operators in object path by @BernieWhite.   #1101</li> </ul> </li> </ul> <p>What's changed since pre-release v2.2.0-B0175:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0175-pre-release","title":"v2.2.0-B0175 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0131:</p> <ul> <li>Bug fixes:<ul> <li>Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite.   #1140</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0131-pre-release","title":"v2.2.0-B0131 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0089:</p> <ul> <li>General improvements:<ul> <li>Added descendant selector to object path syntax by @BernieWhite.   #1133<ul> <li>Use <code>..</code> to traverse into child objects, for example <code>$..name</code> finds names for all nested objects.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to 13.0.1.   #1137</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0089-pre-release","title":"v2.2.0-B0089 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0052:</p> <ul> <li>General improvements:<ul> <li>Improved reporting of the object path that caused rule failures by @BernieWhite.   #1092<ul> <li>Output include a new <code>Detail</code> property with details of the reason and the object path.</li> <li>Custom methods <code>ReasonFrom</code> and <code>ReasonIf</code> accept a <code>path</code> parameter to specify the object path.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0052-pre-release","title":"v2.2.0-B0052 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0021:</p> <ul> <li>General improvements:<ul> <li>Added informational message when output has been written to disk by @BernieWhite.   #1074<ul> <li>The <code>Output.Footer</code> option now supports <code>OutputFile</code> which reports the output file path.   This is enabled by default.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Added more object path tests by @ArmaanMcleod.   #1110</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed output of reason with wide format by @BernieWhite.   #1117</li> <li>Fixed piped input does not respect excluded paths by @BernieWhite.   #1114<ul> <li>By default, objects are not excluded by source.</li> <li>To exclude piped input based on source configure the <code>Input.IgnoreObjectSource</code> option.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0021-pre-release","title":"v2.2.0-B0021 (pre-release)","text":"<p>What's changed since v2.1.0:</p> <ul> <li>New features:<ul> <li>Added <code>notCount</code> expression and assertion helper by @ArmaanMcleod.   #1091</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit.runner.visualstudio to 2.4.5.   #1084</li> <li>Bump Pester to 5.3.3.   #1079</li> <li>Bump Microsoft.NET.Test.Sdk to 17.2.0.   #1089</li> <li>Added NuGet packaging publishing by @BernieWhite.   #1093</li> <li>Updated NuGet packaging metadata by @BernieWhite.   #1093</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed grouping of logical operators in object path by @BernieWhite.   #1101</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v210","title":"v2.1.0","text":"<p>What's changed since v2.0.1:</p> <ul> <li>General improvements:<ul> <li>Added <code>notStartsWith</code>, <code>notEndsWith</code>, and <code>notContains</code> expressions and assertion helpers. #1047</li> <li>Added <code>like</code>, <code>notLike</code> expressions and assertion helpers. #1048</li> <li>Added additional repository paths to ignore by default. #1043</li> <li>Added custom suppression message during PSRule runs. #1046<ul> <li>When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.</li> <li>Configure the suppression group synopsis to display a custom message.</li> <li>Suppression groups synopsis can be localized using markdown documentation.</li> <li>Use markdown to set a culture specific synopsis.</li> <li>Custom suppression messages are not supported when suppressing individual rules using <code>ps-rule.yaml</code>.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> <li>Added source support for string conditions. #1068</li> </ul> </li> <li>Engineering:<ul> <li>Added code signing of module. #1049</li> <li>Added SBOM manifests to module. #1050</li> <li>Bump Sarif.Sdk to 2.4.15. #1075</li> <li>Bump Pester to 5.3.2. #1062</li> </ul> </li> <li>Bug fixes:<ul> <li>Important change: Fixed source scope not updated in multi-module runs. #1053<ul> <li>Several properties of rule and language block elements have been renamed to improve consistency.</li> <li>From v3 custom scripts may not work correctly until you update these names.</li> <li>For details on the updated property names see deprecations.</li> </ul> </li> </ul> </li> </ul> <p>What's changed since pre-release v2.1.0-B0069:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v210-b0069-pre-release","title":"v2.1.0-B0069 (pre-release)","text":"<p>What's changed since pre-release v2.1.0-B0040:</p> <ul> <li>General improvements:<ul> <li>Added <code>notStartsWith</code>, <code>notEndsWith</code>, and <code>notContains</code> expressions and assertion helpers. #1047</li> <li>Added <code>like</code>, <code>notLike</code> expressions and assertion helpers. #1048</li> <li>Added additional repository paths to ignore by default. #1043</li> </ul> </li> <li>Engineering:<ul> <li>Bump Sarif.Sdk to 2.4.15. #1075</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v210-b0040-pre-release","title":"v2.1.0-B0040 (pre-release)","text":"<p>What's changed since pre-release v2.1.0-B0015:</p> <ul> <li>General improvements:<ul> <li>Added custom suppression message during PSRule runs. #1046<ul> <li>When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.</li> <li>Configure the suppression group synopsis to display a custom message.</li> <li>Suppression groups synopsis can be localized using markdown documentation.</li> <li>Use markdown to set a culture specific synopsis.</li> <li>Custom suppression messages are not supported when suppressing individual rules using <code>ps-rule.yaml</code>.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> <li>Added source support for string conditions. #1068</li> </ul> </li> <li>Engineering:<ul> <li>Bump Sarif.Sdk to 2.4.14. #1064</li> <li>Bump Pester to 5.3.2. #1062</li> </ul> </li> <li>Bug fixes:<ul> <li>Important change: Fixed source scope not updated in multi-module runs. #1053<ul> <li>Several properties of rule and language block elements have been renamed to improve consistency.</li> <li>From v3 custom scripts may not work correctly until you update these names.</li> <li>For details on the updated property names see deprecations.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v210-b0015-pre-release","title":"v2.1.0-B0015 (pre-release)","text":"<p>What's changed since v2.0.1:</p> <ul> <li>Engineering:<ul> <li>Added code signing of module. #1049</li> <li>Added SBOM manifests to module. #1050</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v201","title":"v2.0.1","text":"<p>What's changed since v2.0.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed read JSON failed with comments. #1051</li> <li>Fixed null reference on elapsed time when required module check fails. #1054</li> <li>Fixed failed to read JSON objects with a empty property name. #1052</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200","title":"v2.0.0","text":"<p>What's changed since v1.11.1:</p> <ul> <li>New features:<ul> <li>Add support for suppression groups. #793<ul> <li>New <code>SuppressionGroup</code> resource has been included.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> <li>Added source expression property. #933<ul> <li>Included the following expressions:<ul> <li><code>source</code></li> <li><code>withinPath</code></li> <li><code>notWithinPath</code></li> </ul> </li> </ul> </li> <li>Added support for rule severity level. #880<ul> <li>Rules can be configured to be <code>Error</code>, <code>Warning</code>, or <code>Information</code>.</li> <li>Failing rules with the <code>Error</code> severity level will cause the pipeline to fail.</li> <li>Rules with the <code>Warning</code> severity level will be reported as warnings.</li> <li>Rules with the <code>Information</code> severity level will be reported as informational messages.</li> <li>By default, the severity level for a rule is <code>Error</code>.</li> </ul> </li> <li>Added expression support for type based assertions. #908<ul> <li>Included the following expressions:<ul> <li><code>IsArray</code></li> <li><code>IsBoolean</code></li> <li><code>IsDateTime</code></li> <li><code>IsInteger</code></li> <li><code>IsNumeric</code></li> </ul> </li> </ul> </li> <li>Added support for formatting results as SARIF. #878<ul> <li>Set <code>Output.Format</code> to <code>Sarif</code> to output results in the SARIF format.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Add option to disable invariant culture warning. #899<ul> <li>Added <code>Execution.InvariantCultureWarning</code> option.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added support for object path expressions. #808 #693<ul> <li>Inspired by JSONPath, object path expressions can be used to access nested objects.</li> <li>Array members can be filtered and enumerated using object path expressions.</li> <li>Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improve tracking of suppressed objects. #794<ul> <li>Added <code>Execution.SuppressedRuleWarning</code> option to output warning for suppressed rules.</li> </ul> </li> <li>Added support for rule aliases. #792<ul> <li>Aliases allow rules to be references by an alternative name.</li> <li>When renaming rules, add a rule alias to avoid breaking references to the old rule name.</li> <li>To specify an alias use the <code>-Alias</code> parameter or <code>alias</code> metadata property in YAML or JSON.</li> </ul> </li> <li>Added support for stable identifiers with rule refs. #881<ul> <li>A rule ref may be optionally be used to reference a rule.</li> <li>Rule refs should be:   stable, not changing between releases;   opaque, as opposed to being a human-readable string.   Stable and opaque refs ease web lookup and to help to avoid language difficulties.</li> <li>To specify a rule ref use the <code>-Ref</code> parameter or <code>ref</code> metadata property in YAML or JSON.</li> </ul> </li> <li>Added new properties for module lookup to SARIF results. #951</li> <li>Capture and output repository info in Assert-PSRule runs. #978<ul> <li>Added <code>Repository.Url</code> option set repository URL reported in output.</li> <li>Repository URL is detected automatically for GitHub Actions and Azure Pipelines.</li> <li>Added <code>RepositoryInfo</code> to <code>Output.Banner</code> option.</li> <li>Repository info is shown by default.</li> </ul> </li> <li>Added <code>convert</code> and <code>caseSensitive</code> to string comparison expressions. #1001<ul> <li>The following expressions support type conversion and case-sensitive comparison.<ul> <li><code>startsWith</code>, <code>contains</code>, and <code>endsWith</code>.</li> <li><code>equals</code> and <code>notEquals</code>.</li> </ul> </li> </ul> </li> <li>Added <code>convert</code> to numeric comparison expressions. #943<ul> <li>Type conversion is now supported for <code>less</code>, <code>lessOrEquals</code>, <code>greater</code>, and <code>greaterOrEquals</code>.</li> </ul> </li> <li>Added <code>Extent</code> property on rules reported by <code>Get-PSRule</code>. #990<ul> <li>Extent provides the line and position of the rule in the source code.</li> </ul> </li> <li>Breaking change: Added validation of resource names. #1012<ul> <li>Invalid rules names will now produce a specific error.</li> <li>See upgrade notes for more information.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removal of deprecated default baseline from module manifest. #755<ul> <li>Set the default module baseline using module configuration.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Require <code>apiVersion</code> on YAML and JSON to be specified. #648<ul> <li>Resources should use <code>github.com/microsoft/PSRule/v1</code> as the <code>apiVersion</code>.</li> <li>Resources that do not specify an <code>apiVersion</code> will be ignored.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Prefer module sources over loose files. #610<ul> <li>Module sources are discovered before loose files.</li> <li>Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Require rule sources from current working directory to be explicitly included. #760<ul> <li>From v2 onwards, <code>$PWD</code> is not included by default unless <code>-Path .</code> or <code>-Path $PWD</code> is explicitly specified.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Added more tests for JSON resources. #929</li> <li>Bump Sarif.Sdk to 2.4.13. #1007</li> <li>Bump PowerShellStandard.Library to 5.1.1. #999</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed object path handling with dash. #902</li> <li>Fixed empty suppression group rules property applies to no rules. #931</li> <li>Fixed object reference for suppression group will rule not defined. #932</li> <li>Fixed rule source loading twice from <code>$PWD</code> and <code>.ps-rule/</code>. #939</li> <li>Fixed rule references in SARIF format for extensions need a toolComponent reference. #949</li> <li>Fixed file objects processed with file input format have no source location. #950</li> <li>Fixed GitHub code scanning alerts treats pass as problems. #955<ul> <li>By default, SARIF output will only include fail or error outcomes.</li> <li>Added <code>Output.SarifProblemsOnly</code> option to include pass outcomes.</li> </ul> </li> <li>Fixed SARIF output includes rule property for default tool component. #956</li> <li>Fixed Invoke-PSRule hanging if JSON rule file is empty. #969</li> <li>Fixed SARIF should report base branch. #964</li> <li>Fixed unclear error message on invalid rule names. #1012</li> </ul> </li> </ul> <p>What's changed since pre-release v2.0.0-B2203045:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2203045-pre-release","title":"v2.0.0-B2203045 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2203033:</p> <ul> <li>General improvements:<ul> <li>Added <code>convert</code> to numeric comparison expressions. #943<ul> <li>Type conversion is now supported for <code>less</code>, <code>lessOrEquals</code>, <code>greater</code>, and <code>greaterOrEquals</code>.</li> </ul> </li> <li>Breaking change: Added validation of resource names. #1012<ul> <li>Invalid rules names will now produce a specific error.</li> <li>See upgrade notes for more information.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed unclear error message on invalid rule names. #1012</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2203033-pre-release","title":"v2.0.0-B2203033 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2203019:</p> <ul> <li>General improvements:<ul> <li>Added <code>Extent</code> property on rules reported by <code>Get-PSRule</code>. #990<ul> <li>Extent provides the line and position of the rule in the source code.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Sarif.Sdk to 2.4.13. #1007</li> <li>Bump PowerShellStandard.Library to 5.1.1. #999</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2203019-pre-release","title":"v2.0.0-B2203019 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202072:</p> <ul> <li>General improvements:<ul> <li>Added <code>convert</code> and <code>caseSensitive</code> to string comparison expressions. #1001<ul> <li>The following expressions support type conversion and case-sensitive comparison.<ul> <li><code>startsWith</code>, <code>contains</code>, and <code>endsWith</code>.</li> <li><code>equals</code> and <code>notEquals</code>.</li> </ul> </li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202072-pre-release","title":"v2.0.0-B2202072 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202065:</p> <ul> <li>General improvements:<ul> <li>Capture and output repository info in Assert-PSRule runs. #978<ul> <li>Added <code>Repository.Url</code> option set repository URL reported in output.</li> <li>Repository URL is detected automatically for GitHub Actions and Azure Pipelines.</li> <li>Added <code>RepositoryInfo</code> to <code>Output.Banner</code> option.</li> <li>Repository info is shown by default.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed SARIF should report base branch. #964</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202065-pre-release","title":"v2.0.0-B2202065 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202056:</p> <ul> <li>Bug fixes:<ul> <li>Fixed broken documentation links. #980</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202056-pre-release","title":"v2.0.0-B2202056 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202024:</p> <ul> <li>Bug fixes:<ul> <li>Fixed Invoke-PSRule hanging if JSON rule file is empty. #969</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202024-pre-release","title":"v2.0.0-B2202024 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202017:</p> <ul> <li>New features:<ul> <li>Added source expression property. #933<ul> <li>Included the following expressions:<ul> <li><code>source</code></li> <li><code>withinPath</code></li> <li><code>notWithinPath</code></li> </ul> </li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202017-pre-release","title":"v2.0.0-B2202017 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202006:</p> <ul> <li>Bug fixes:<ul> <li>Fixed GitHub code scanning alerts treats pass as problems. #955<ul> <li>By default, SARIF output will only include fail or error outcomes.</li> <li>Added <code>Output.SarifProblemsOnly</code> option to include pass outcomes.</li> </ul> </li> <li>Fixed SARIF output includes rule property for default tool component. #956</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202006-pre-release","title":"v2.0.0-B2202006 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201161:</p> <ul> <li>General improvements:<ul> <li>Added new properties for module lookup to SARIF results. #951</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed rule references in SARIF format for extensions need a toolComponent reference. #949</li> <li>Fixed file objects processed with file input format have no source location. #950</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201161-pre-release","title":"v2.0.0-B2201161 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201146:</p> <ul> <li>New features:<ul> <li>Added support for rule severity level. #880<ul> <li>Rules can be configured to be <code>Error</code>, <code>Warning</code>, or <code>Information</code>.</li> <li>Failing rules with the <code>Error</code> severity level will cause the pipeline to fail.</li> <li>Rules with the <code>Warning</code> severity level will be reported as warnings.</li> <li>Rules with the <code>Information</code> severity level will be reported as informational messages.</li> <li>By default, the severity level for a rule is <code>Error</code>.</li> </ul> </li> <li>Added expression support for type based assertions. #908<ul> <li>Included the following expressions:<ul> <li><code>IsArray</code></li> <li><code>IsBoolean</code></li> <li><code>IsDateTime</code></li> <li><code>IsInteger</code></li> <li><code>IsNumeric</code></li> </ul> </li> </ul> </li> <li>Added support for formatting results as SARIF. #878<ul> <li>Set <code>Output.Format</code> to <code>Sarif</code> to output results in the SARIF format.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201146-pre-release","title":"v2.0.0-B2201146 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201135:</p> <ul> <li>Engineering:<ul> <li>Breaking change: Require rule sources from current working directory to be explicitly included. #760<ul> <li>From v2 onwards, <code>$PWD</code> is not included by default unless <code>-Path .</code> or <code>-Path $PWD</code> is explicitly specified.</li> <li>See upgrade notes for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed rule source loading twice from <code>$PWD</code> and <code>.ps-rule/</code>. #939</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201135-pre-release","title":"v2.0.0-B2201135 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201117:</p> <ul> <li>Engineering:<ul> <li>Breaking change: Prefer module sources over loose files. #610<ul> <li>Module sources are discovered before loose files.</li> <li>Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Added more tests for JSON resources. #929</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed empty suppression group rules property applies to no rules. #931</li> <li>Fixed object reference for suppression group will rule not defined. #932</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201117-pre-release","title":"v2.0.0-B2201117 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201093:</p> <ul> <li>General improvements:<ul> <li>Add option to disable invariant culture warning. #899<ul> <li>Added <code>Execution.InvariantCultureWarning</code> option.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201093-pre-release","title":"v2.0.0-B2201093 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201075:</p> <ul> <li>New features:<ul> <li>Add support for suppression groups. #793<ul> <li>New <code>SuppressionGroup</code> resource has been included.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201075-pre-release","title":"v2.0.0-B2201075 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201054:</p> <ul> <li>General improvements:<ul> <li>Added support for rule aliases. #792<ul> <li>Aliases allow rules to be references by an alternative name.</li> <li>When renaming rules, add a rule alias to avoid breaking references to the old rule name.</li> <li>To specify an alias use the <code>-Alias</code> parameter or <code>alias</code> metadata property in YAML or JSON.</li> </ul> </li> <li>Added support for stable identifiers with rule refs. #881<ul> <li>A rule ref may be optionally be used to reference a rule.</li> <li>Rule refs should be:   stable, not changing between releases;   opaque, as opposed to being a human-readable string.   Stable and opaque refs ease web lookup and to help to avoid language difficulties.</li> <li>To specify a rule ref use the <code>-Ref</code> parameter or <code>ref</code> metadata property in YAML or JSON.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed object path handling with dash. #902</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201054-pre-release","title":"v2.0.0-B2201054 (pre-release)","text":"<p>What's changed since v1.11.0:</p> <ul> <li>General improvements:<ul> <li>Added support for object path expressions. #808 #693<ul> <li>Inspired by JSONPath, object path expressions can be used to access nested objects.</li> <li>Array members can be filtered and enumerated using object path expressions.</li> <li>Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improve tracking of suppressed objects. #794<ul> <li>Added <code>Execution.SuppressedRuleWarning</code> option to output warning for suppressed rules.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removal of deprecated default baseline from module manifest. #755<ul> <li>Set the default module baseline using module configuration.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Require <code>apiVersion</code> on YAML and JSON to be specified. #648<ul> <li>Resources should use <code>github.com/microsoft/PSRule/v1</code> as the <code>apiVersion</code>.</li> <li>Resources that do not specify an <code>apiVersion</code> will be ignored.</li> <li>See upgrade notes for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Experimental features:</p> <ul> <li>Baseline groups allow you to use a friendly name to reference baselines.   See baselines for more information.</li> <li>Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition.   See functions for more information.</li> <li>Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties.   See sub-selectors for more information.</li> <li> <p>Processing of changes files only within a pipeline.   See creating your pipeline for more information.</p> </li> </ul>"},{"location":"CHANGELOG-v3/#unreleased","title":"Unreleased","text":"<p>What's changed since pre-release v3.0.0-B0153:</p> <ul> <li>Engineering:<ul> <li>Bump System.Drawing.Common to v8.0.5.   #1817</li> <li>Bump Bump xunit to v2.8.0.   #1809</li> <li>Bump xunit.runner.visualstudio to v2.8.0.   #1808</li> <li>Bump YamlDotNet to v15.1.4.   #1816</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.9.2.   #1773</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed discovery of installed modules in CLI by @BernieWhite.   #1779</li> <li>Fixed for git head in tests by @BernieWhite.   #1801</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0153-pre-release","title":"v3.0.0-B0153 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0151:</p> <ul> <li>Bug fixes:<ul> <li>Fixes null references for CLI module handling by @BernieWhite.   #1746</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0151-pre-release","title":"v3.0.0-B0151 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0141:</p> <ul> <li>General improvements:<ul> <li>Improved support for packaging with Visual Studio Code by @BernieWhite.   #1755</li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Bump development tools to .NET 8.0 SDK by @BernieWhite.   #1673<ul> <li>Running PSRule from PowerShell 7.x is supported on 7.4 and above.</li> <li>Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.</li> </ul> </li> <li>Bump Microsoft.NET.Test.Sdk to v17.9.0.   #1752</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed CLI null reference when include module is undefined by @BernieWhite.   #1746</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0141-pre-release","title":"v3.0.0-B0141 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0137:</p> <ul> <li>General improvements:<ul> <li>SARIF output has been improved to include effective configuration from a run by @BernieWhite.   #1739</li> <li>SARIF output has been improved to include file hashes for source files from a run by @BernieWhite.   #1740</li> <li>Added support to allow disabling PowerShell features that can be run from a repository by @BernieWhite.   #1742<ul> <li>Added the <code>Execution.RestrictScriptSource</code> option to disable running scripts from a repository.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet to v15.1.0.   #1737</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0137-pre-release","title":"v3.0.0-B0137 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0122:</p> <ul> <li>General improvements:<ul> <li>Breaking change: Moved the <code>restore</code> command to a sub-command of <code>module</code> by @BernieWhite.   #1730<ul> <li>The functionality of the <code>restore</code> command is now available as <code>module restore</code>.</li> </ul> </li> <li>Added CLI commands to list and report status of locked modules by @BernieWhite.   #1729<ul> <li>Added <code>module init</code> sub-command to initialize the lock file from configured options.</li> <li>Added <code>module list</code> sub-command to list locked and unlocked modules associated with the workspace.</li> <li>Added <code>version</code> property to the lock file schema to support versioning of the lock file.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump BenchmarkDotNet to v0.13.12.   #1725</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.12.   #1728</li> <li>Bump xunit to v2.6.6.   #1732</li> <li>Bump xunit.runner.visualstudio to v2.5.6.   #1717</li> <li>Bump System.Drawing.Common to v8.0.1.   #1727</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0122-pre-release","title":"v3.0.0-B0122 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0093:</p> <ul> <li>General improvements:<ul> <li>Breaking change: Renamed <code>analyze</code> CLI command to <code>run</code> by @BernieWhite.   #1713</li> <li>Added <code>--outcome</code> argument for CLI to support filtering output by @bernieWhite.   #1706</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit to v2.6.3.   #1699</li> <li>Bump xunit.runner.visualstudio to v2.5.5.   #1700</li> <li>Bump Microsoft.NET.Test.Sdk to v17.8.0.   #1659</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v8.0.0.   #1674</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.8.0.   #1686</li> <li>Bump BenchmarkDotNet to v0.13.11.   #1694</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.11.   #1697</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0093-pre-release","title":"v3.0.0-B0093 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0084:</p> <ul> <li>Engineering:<ul> <li>Bump xunit to v2.6.1.   #1656</li> <li>Bump System.Drawing.Common to v8.0.0.   #1669</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed CLI IndexOutOfRangeException with lock file by @BernieWhite.   #1676</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0084-pre-release","title":"v3.0.0-B0084 (pre-release)","text":"<p>What's changed since release v2.9.0:</p> <ul> <li>New features:<ul> <li>Added lock file support when using CLI and related tools by @BernieWhite.   #1660<ul> <li>The lock file used used during analysis and when installing modules to select a specific version.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Breaking change: Switch to use SHA-512 for generating unbound objects by @BernieWhite.   #1155<ul> <li>Objects that have no bound name will automatically be assigned a name based on the SHA-512 hash of the object.</li> <li>Previously a SHA-1 hash was used, however this is no longer considered secure.</li> <li>The name for unbound objects that are suppressed will change as a result.</li> <li>Additionally the hash can be changed by setting the <code>Execution.HashAlgorithm</code> option.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Removed deprecated execution options by @BernieWhite.   #1457</li> <li>Breaking change: Removed deprecated object properties by @BernieWhite.   #1601</li> <li>Expanded support for <code>FileHeader</code> assertion by @BernieWhite.   #1521<ul> <li>Added support for <code>.bicepparam</code>, <code>.tsp</code>, <code>.tsx</code>, <code>.editorconfig</code>, <code>.ipynb</code>, and <code>.toml</code> files.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Bump development tools to .NET 7.0 SDK by @BernieWhite.   #1631<ul> <li>Running PSRule from PowerShell 7.x is supported on 7.3 and above.</li> <li>Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.</li> </ul> </li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.4.   #1602</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.7.0.   #1593</li> <li>Bump Microsoft.NET.Test.Sdk to v17.7.2.   #1608</li> <li>Bump YamlDotNet to v13.7.1.   #1647</li> <li>Bump xunit to v2.5.3.   #1648</li> <li>Bump xunit.runner.visualstudio to v2.5.3.   #1644</li> <li>Bump BenchmarkDotNet to v0.13.10.   #1654</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.10.   #1654</li> </ul> </li> </ul>"},{"location":"about/","title":"What is PSRule?","text":"<p>PSRule is a rules engine geared towards testing Infrastructure as Code (IaC). Rules you write or import perform static analysis on IaC artifacts such as: templates, manifests, pipelines, and workflows.</p>"},{"location":"about/#why-use-psrule","title":"Why use PSRule?","text":"<p>PSRule aims to provide a rich experience for building and running static analysis tests on IaC. While this has some similarities to traditional testing frameworks it extends on the following:</p> <ul> <li>Reuse and share \u2014 existing pre-built rules, configure, or write your own.</li> <li>Incremental adoption \u2014 with baselines allows you to keep moving forward.</li> <li>Handle exceptions \u2014 and keep exceptions auditable in git history.</li> <li>Documentation \u2014 provides recommendations and examples instead of just pass or fail.</li> </ul>"},{"location":"addon-modules/","title":"Additional modules","text":""},{"location":"addon-modules/#integrations","title":"Integrations","text":""},{"location":"addon-modules/#azure-monitor","title":"Azure Monitor","text":"<p>You can send rule results to Azure Monitor using <code>PSRule.Monitor</code>.</p> <p></p>"},{"location":"addon-modules/#pre-built-rules","title":"Pre-built rules","text":"<p>The following modules contain pre-built rules that can be plugged into your pipeline.</p> Module Description Version / downloads PSRule.Rules.Azure A suite of rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements. PSRule.Monitor Log PSRule analysis results to Azure Monitor."},{"location":"analysis-output/","title":"Analysis output","text":"<p>PSRule supports generating and saving output in a number of different formats.</p> <p>Abstract</p> <p>This topic covers the supported formats and options for presenting output from a PSRule run.</p>"},{"location":"analysis-output/#setting-the-output-format","title":"Setting the output format","text":"<p>The output format can be configuring by setting the <code>Output.Format</code> option to one the following:</p> <ul> <li><code>Yaml</code> - Output is serialized as YAML.</li> <li><code>Json</code> - Output is serialized as JSON.</li> <li><code>Markdown</code> - Output is serialized as Markdown.</li> <li><code>NUnit3</code> - Output is serialized as NUnit3 (XML).</li> <li><code>Csv</code> - Output is serialized as a comma-separated values (CSV).</li> <li><code>Sarif</code> - Output is serialized as SARIF.</li> </ul> <p>Tip</p> <p>To write output to a file, also set the <code>Output.Path</code> option to the file path to save.</p> GitHub ActionsAzure PipelinesPowerShellOptions file <pre><code># Analyze and save results\n- name: Analyze repository\n  uses: microsoft/ps-rule@v2.9.0\n  with:\n    outputFormat: Sarif\n    outputPath: reports/ps-rule-results.sarif\n</code></pre> <pre><code># Analyze and save results\n- task: ps-rule-assert@2\n  displayName: Analyze repository\n  inputs:\n    inputType: repository\n    outputFormat: Sarif\n    outputPath: reports/ps-rule-results.sarif\n</code></pre> Invoke-PSRule<pre><code>Invoke-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n</code></pre> Assert-PSRule<pre><code>Assert-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n</code></pre> ps-rule.yaml<pre><code>output:\n  format: 'Sarif'\n  path: reports/ps-rule-results.sarif\n</code></pre>"},{"location":"analysis-output/#formatting-as-yaml","title":"Formatting as YAML","text":"<p>When using the YAML output format, results a serialized as YAML. Two spaces are used to indent properties of objects.</p> Example output <pre><code>- data: {}\n  info:\n    displayName: Local.PS.RequireTLS\n    name: Local.PS.RequireTLS\n    synopsis: An example rule to require TLS.\n  level: Error\n  outcome: Fail\n  outcomeReason: Processed\n  reason:\n  - The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\n  - The field 'configure.minTLSVersion' does not exist.\n  ruleName: Local.PS.RequireTLS\n  runId: 16b0534165ffb5279beeb1672a251fc1ff3124b6\n  source:\n  - file: C:\\Dev\\Workspace\\PSRule\\docs\\authoring\\writing-rules\\settings.json\n    line: 2\n    position: 11\n    type: File\n  targetName: 1fe7c0f476b11301402d5017d87424c36ff085a8\n  targetType: app1\n  time: 0\n</code></pre>"},{"location":"analysis-output/#formatting-as-json","title":"Formatting as JSON","text":"<p>When using the JSON output format, results are serialized as JSON. By default, no indentation is used.</p> Example output <pre><code>[{\"data\":{},\"info\":{\"displayName\":\"Local.PS.RequireTLS\",\"name\":\"Local.PS.RequireTLS\",\"synopsis\":\"An example rule to require TLS.\"},\"level\":1,\"outcome\":\"Fail\",\"outcomeReason\":\"Processed\",\"reason\":[\"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\"The field 'configure.minTLSVersion' does not exist.\"],\"ruleName\":\"Local.PS.RequireTLS\",\"runId\":\"df662aad3ae7adee6f35b9733c7aaa53dc4d6b96\",\"source\":[{\"file\":\"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\"line\":2,\"position\":11,\"type\":\"File\"}],\"targetName\":\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"targetType\":\"app1\",\"time\":0}]\n</code></pre>"},{"location":"analysis-output/#configuring-json-indentation","title":"Configuring JSON indentation","text":"<p> v1.8.0</p> <p>The number of spaces used to indent properties and elements is configurable between <code>0</code> to <code>4</code> spaces. By default, no indentation is used.</p> Example output with 2 spaces <pre><code>[\n  {\n    \"data\": {},\n    \"info\": {\n      \"displayName\": \"Local.PS.RequireTLS\",\n      \"name\": \"Local.PS.RequireTLS\",\n      \"synopsis\": \"An example rule to require TLS.\"\n    },\n    \"level\": 1,\n    \"outcome\": \"Fail\",\n    \"outcomeReason\": \"Processed\",\n    \"reason\": [\n      \"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\n      \"The field 'configure.minTLSVersion' does not exist.\"\n    ],\n    \"ruleName\": \"Local.PS.RequireTLS\",\n    \"runId\": \"3afadfed32e57f5283ad71c1aa496da822ff0c84\",\n    \"source\": [\n      {\n        \"file\": \"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\n        \"line\": 2,\n        \"position\": 11,\n        \"type\": \"File\"\n      }\n    ],\n    \"targetName\": \"1fe7c0f476b11301402d5017d87424c36ff085a8\",\n    \"targetType\": \"app1\",\n    \"time\": 0\n  }\n]\n</code></pre>"},{"location":"analysis-output/#formatting-as-csv","title":"Formatting as CSV","text":"<p>The output from analysis can be formatted as comma-separated values (CSV). Formatting as CSV may be useful when manipulating output results by hand. Output of CSV format varies depending on if detailed or summary output is used.</p> <p>For detailed output, the following columns are added to CSV output for each processed object:</p> Column Description <code>RuleName</code> The name of the rule. <code>TargetName</code> The name of the object that was analyzed. <code>TargetType</code> The type of the object that was analyzed. <code>Outcome</code> The outcome of the analysis, such as <code>Pass</code> or <code>Fail</code>. <code>OutcomeReason</code> An additional reason for the outcome such as <code>Inconclusive</code>. <code>Synopsis</code> A short description of the rule. <code>Recommendation</code> The recommendation of the rule. <p>For summary output, the following columns are used:</p> Column Description <code>RuleName</code> The name of the rule. <code>Pass</code> The number of objects that passed. <code>Fail</code> The number of objects that failed. <code>Outcome</code> The worst case outcome of the analysis, such as <code>Pass</code> or <code>Fail</code>. <code>Synopsis</code> A short description of the rule. <code>Recommendation</code> The recommendation of the rule. Example output <pre><code>RuleName,TargetName,TargetType,Outcome,OutcomeReason,Synopsis,Recommendation\n\"Local.PS.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.YAML.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.JSON.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n</code></pre>"},{"location":"analysis-output/#formatting-as-sarif","title":"Formatting as SARIF","text":"<p> v2.0.0</p> <p>Static Analysis Results Interchange Format (SARIF) is a standard output format for static analysis tools. It enables various unrelated tools to consume analysis results from PSRule. You can use SARIF to perform Static Analysis Security Testing (SAST) in DevOps environments at-scale.</p>"},{"location":"analysis-output/#github-code-scanning-alerts","title":"GitHub code scanning alerts","text":"<p>SARIF results from PSRule can be uploaded to GitHub to create code scanning alerts against a repository. You can see these results in your repository visible under Security &gt; Code scanning alerts.</p> <p>Tip</p> <p>Code scanning is available for all public repositories, and for private repositories owned by organizations where GitHub Advanced Security is enabled. For more information, see About GitHub Advanced Security.</p> <p>To configure GitHub Actions, perform the following steps:</p> <ul> <li>Create a GitHub Actions workflow.</li> <li>Add a step using the <code>microsoft/ps-rule</code> action.<ul> <li>Configure the <code>outputFormat</code> and <code>outputPath</code> parameters.</li> </ul> </li> <li>Add a step using the <code>github/codeql-action/upload-sarif</code> action.<ul> <li>Configure the <code>sarif_file</code> parameter to the same file path specified in <code>outputPath</code>.</li> </ul> </li> </ul> <p>Example <code>.github/workflows/analyze.yaml</code></p> <pre><code>name: Analyze\non:\n  push:\n    branches: [ main ]\n  schedule:\n  - cron: '24 22 * * 0' # At 10:24 PM, on Sunday each week\n  workflow_dispatch:\n\njobs:\n  oss:\n    name: Analyze with PSRule\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      security-events: write\n    steps:\n\n    - name: Checkout\n      uses: actions/checkout@v4\n\n    - name: Run PSRule analysis\n      uses: microsoft/ps-rule@v2.9.0\n      with:\n        outputFormat: Sarif\n        outputPath: reports/ps-rule-results.sarif\n\n    - name: Upload results to security tab\n      uses: github/codeql-action/upload-sarif@v3\n      with:\n        sarif_file: reports/ps-rule-results.sarif\n</code></pre>"},{"location":"analysis-output/#azure-devops-scans-tab","title":"Azure DevOps scans tab","text":"<p>SARIF results from PSRule can be uploaded and viewed within Azure DevOps. To add the scans tab to build results the SARIF SAST Scans Tab extension needs to be installed.</p>"},{"location":"analysis-output/#verifying-configuration","title":"Verifying configuration","text":"<p> v3.0.0</p> <p>The configuration used to run PSRule is included in properties of the run. This can be used to verify the configuration used to run PSRule.</p>"},{"location":"creating-your-pipeline/","title":"Creating your pipeline","text":"<p>You can use PSRule to test Infrastructure as Code (IaC) artifacts throughout their lifecycle. By using validation within a continuous integration (CI) pipeline, any issues provide fast feedback.</p> <p>Within the root directory of your IaC repository:</p> GitHub ActionsAzure PipelinesGeneric with PowerShell <p>Create a new GitHub Actions workflow by creating <code>.github/workflows/analyze-arm.yaml</code>.</p> <pre><code>name: Analyze templates\non:\n- pull_request\njobs:\n  analyze_arm:\n    name: Analyze templates\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: Checkout\n      uses: actions/checkout@v4\n\n    # Analyze Azure resources using PSRule for Azure\n    - name: Analyze Azure template files\n      uses: microsoft/ps-rule@v2.9.0\n      with:\n        modules: 'PSRule.Rules.Azure'\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p> <p>Create a new Azure DevOps YAML pipeline by creating <code>.azure-pipelines/analyze-arm.yaml</code>.</p> <pre><code>steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n  displayName: Analyze Azure template files\n  inputs:\n    inputType: repository\n    modules: 'PSRule.Rules.Azure'\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p> <p>Create a pipeline in any CI environment by using PowerShell.</p> <pre><code>$modules = @('PSRule.Rules.Azure')\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\n</code></pre> <p>Tip</p> <p>This example demonstrates using PSRule for Azure, a populate module for testing Azure IaC. Instead, you can write your own module or use one of our pre-built modules.</p>"},{"location":"creating-your-pipeline/#configuration","title":"Configuration","text":"<p>Configuration options for PSRule are set within the <code>ps-rule.yaml</code> file.</p>"},{"location":"creating-your-pipeline/#ignoring-rules","title":"Ignoring rules","text":"<p>To prevent a rule executing you can either:</p> <ul> <li>Exclude rules by name \u2014 The rule is not executed for any object.</li> <li>Suppress rules by name \u2014 The rule is not executed for a specific object by name.</li> <li>Suppress rules by condition \u2014 The rule is not executed for matching objects.</li> </ul> Exclude by nameSuppression by nameSuppression by condition <p>To exclude a rule, set <code>Rule.Exclude</code> option within the <code>ps-rule.yaml</code> file.</p> <p>[ Docs][3]</p> ps-rule.yaml<pre><code>rule:\n  exclude:\n  # Ignore the following rules for all objects\n  - Azure.VM.UseHybridUseBenefit\n  - Azure.VM.Standalone\n</code></pre> <p>To suppress an individual rule, set <code>Suppression</code> option within the <code>ps-rule.yaml</code> file.</p> <p>[ Docs][4]</p> ps-rule.yaml<pre><code>suppression:\n  Azure.AKS.AuthorizedIPs:\n  # Exclude the following externally managed AKS clusters\n  - aks-cluster-prod-eus-001\n  Azure.Storage.SoftDelete:\n  # Exclude the following non-production storage accounts\n  - storagedeveus6jo36t\n  - storagedeveus1df278\n</code></pre> <p>To suppress an rules by condition, create a suppression group.</p> <p>[ Docs][5]</p> <pre><code>---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: SuppressWithTargetName\nspec:\n  rule:\n  - 'FromFile1'\n  - 'FromFile2'\n  if:\n    name: '.'\n    in:\n    - 'TestObject1'\n    - 'TestObject2'\n</code></pre> <p>Tip</p> <p>Use comments within <code>ps-rule.yaml</code> to describe the reason why rules are excluded or suppressed. Meaningful comments help during peer review within a Pull Request (PR). Also consider including a date if the exclusions or suppressions are temporary.</p>"},{"location":"creating-your-pipeline/#processing-changed-files-only","title":"Processing changed files only","text":"<p> v2.5.0 \u00b7  Docs</p> <p>To only process files that have changed within a pull request, set the <code>Input.IgnoreUnchangedPath</code> option.</p> GitHub ActionsAzure PipelinesGeneric with PowerShell <p>Update your GitHub Actions workflow by setting the <code>PSRULE_INPUT_IGNOREUNCHANGEDPATH</code> environment variable.</p> .github/workflows/analyze-arm.yaml<pre><code>name: Analyze templates\non:\n- pull_request\njobs:\n  analyze_arm:\n    name: Analyze templates\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: Checkout\n      uses: actions/checkout@v4\n\n    # Analyze Azure resources using PSRule for Azure\n    - name: Analyze Azure template files\n      uses: microsoft/ps-rule@v2.9.0\n      with:\n        modules: 'PSRule.Rules.Azure'\n      env:\n        PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n</code></pre> <p>Update your Azure DevOps YAML pipeline by setting the <code>PSRULE_INPUT_IGNOREUNCHANGEDPATH</code> environment variable.</p> .azure-pipelines/analyze-arm.yaml<pre><code>steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n  displayName: Analyze Azure template files\n  inputs:\n    inputType: repository\n    modules: 'PSRule.Rules.Azure'\n  env:\n    PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n</code></pre> <p>Update your PowerShell command-line to include the <code>Input.IgnoreUnchangedPath</code> option.</p> PowerShell<pre><code>$modules = @('PSRule.Rules.Azure')\n$options = @{\n    'Input.IgnoreUnchangedPath' = $True\n}\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -Options $options -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\n</code></pre> <p>Tip</p> <p>In some cases it may be necessary to set <code>Repository.BaseRef</code> to the default branch of your repository. By default, PSRule will detect the default branch of the repository from the build system environment variables.</p>"},{"location":"deprecations/","title":"Deprecations","text":""},{"location":"deprecations/#deprecations-for-v3","title":"Deprecations for v3","text":""},{"location":"deprecations/#execution-options","title":"Execution options","text":"<p>PSRule provides a number of execution options that control logging of certain events. In many cases these options turn a warning on or off.</p> <p>These options are deprecated but replaced to provide more choice to when configuring logging options. Now you can configure the following:</p> <ul> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>The following execution options have been deprecated and will be removed from v3.</p> <ul> <li><code>Execution.SuppressedRuleWarning</code> is replaced with <code>Execution.RuleSuppressed</code>.   Set <code>Execution.RuleSuppressed</code> to <code>Warn</code> to log a warning from v2.8.0.   If both options are set, <code>Execution.SuppressedRuleWarning</code> takes precedence until v3.</li> <li><code>Execution.AliasReferenceWarning</code> is replaced with <code>Execution.AliasReference</code>.   Set <code>Execution.AliasReference</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.AliasReferenceWarning</code> takes precedence until v3.</li> <li><code>Execution.InconclusiveWarning</code> is replaced with <code>Execution.RuleInconclusive</code>.   Set <code>Execution.RuleInconclusive</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.InconclusiveWarning</code> takes precedence until v3.</li> <li><code>Execution.InvariantCultureWarning</code> is replaced with <code>Execution.InvariantCulture</code>.   Set <code>Execution.InvariantCulture</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.InvariantCultureWarning</code> takes precedence until v3.</li> <li><code>Execution.NotProcessedWarning</code> is replaced with <code>Execution.UnprocessedObject</code>.   Set <code>Execution.UnprocessedObject</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.NotProcessedWarning</code> takes precedence until v3.</li> </ul> <p>Tip</p> <p>You do not need to configure both options. If you have the deprecated option configured, switch to the new option.</p>"},{"location":"deprecations/#git-head-input-object","title":"Git Head input object","text":"<p>Previously when the <code>Input.Format</code> option was set to <code>File</code> the <code>.git/HEAD</code> file was emitted as an input object. The original purpose of this feature was to allow conventions to run once against the root of the repository. Subsequent changes to PSRule have made this feature redundant by adding support for the <code>-Initialize</code> block.</p> <p>From v3 the <code>.git/HEAD</code> file will no longer be emitted as an input object.</p> <p>Consider adding or updating a convention that uses the <code>-Initialize</code> block to emit run initialization logic. Yon can also use the <code>-Initialize</code> block to emit a custom object to the pipeline by using the <code>$PSRule.ImportWithType</code> method.</p>"},{"location":"deprecations/#rule-output-object","title":"Rule output object","text":"<p>Several properties of the rule object have been renamed to improve consistency with other objects. Previously rules returned by <code>Get-PSRule</code> returned a rule object which included the following properties:</p> <ul> <li><code>RuleId</code></li> <li><code>RuleName</code></li> <li><code>Description</code></li> <li><code>ModuleName</code></li> <li><code>SourcePath</code></li> </ul> <p>These have been replaced with the following properties:</p> <ul> <li><code>Id</code> instead of <code>RuleId</code>.</li> <li><code>Name</code> instead of <code>RuleName</code>.</li> <li><code>Synopsis</code> instead of <code>Description</code>.</li> <li><code>Source.Module</code> instead of <code>ModuleName</code>.</li> <li><code>Source.Path</code> instead of <code>SourcePath</code>.</li> </ul> <p>The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.</p>"},{"location":"deprecations/#language-block-interface","title":"Language block interface","text":"<p>Several properties of Baselines and Selectors have been renamed to improve consistency.</p> <ul> <li><code>ModuleName</code></li> <li><code>SourcePath</code></li> </ul> <p>These have been replaced with the following properties:</p> <ul> <li><code>Source.Module</code> instead of <code>ModuleName</code>.</li> <li><code>Source.Path</code> instead of <code>SourcePath</code>.</li> </ul> <p>The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.</p>"},{"location":"deprecations/#deprecations-for-v2","title":"Deprecations for v2","text":""},{"location":"deprecations/#default-baseline-by-module-manifest","title":"Default baseline by module manifest","text":"<p>When packaging baselines in a module, you may want to specify a default baseline. PSRule v1.9.0 added support for setting the default baseline in a module configuration.</p> <p>Previously a default baseline could be set by specifying the baseline in the module manifest. From v1.9.0 this is deprecated and will be removed from v2.</p> <p>For details on how to migrate to the new default baseline option, continue reading the upgrade notes.</p>"},{"location":"deprecations/#resources-without-an-api-version","title":"Resources without an API version","text":"<p>When creating YAML and JSON resources you define a resource by specifying the <code>apiVersion</code> and <code>kind</code>. To allow new schema versions for resources to be introduced in the future, an <code>apiVersion</code> was introduced. For backwards compatibility, resources without an <code>apiVersion</code> deprecated but supported. From v2 resources without an <code>apiVersion</code> will be ignored.</p> <p>For details on how to add an <code>apiVersion</code> to a resource, continue reading the upgrade notes.</p>"},{"location":"faq/","title":"Frequently Asked Questions (FAQ)","text":""},{"location":"faq/#how-is-psrule-different-to-pester","title":"How is PSRule different to Pester?","text":"<p>PSRule is a framework for testing infrastructure as code (IaC) and objects using rules. Rules can be written in PowerShell, YAML, or JSON. Some features include:</p> <ul> <li>Objects - PowerShell objects can be validated on the pipeline or imported.<ul> <li>Objects can be imported directly from <code>JSON</code>, <code>YAML</code>, or <code>.psd1</code>.</li> <li>Each object is automatically bound to a target type for use with pre-conditions.</li> <li>Rule results are orientated to validating an object.</li> <li>Built-in assertions, automatically traverse object properties.</li> </ul> </li> <li>Pre-conditions - Rules understand which objects they apply to. Objects are bound to a type as they are processed using object properties. Dissimilar objects can be processed quickly.<ul> <li>Objects that match no rules are flagged with a warning by default.</li> </ul> </li> <li>Packaging - Rules can be reused between projects and optionally packaged into a module.<ul> <li>Portable rules, configuration, baselines, and documentation allow greater reuse and distribution.</li> <li>Documentation with detailed guidance or next steps can be included.</li> <li>Standalone or rules from modules can be combined together with <code>-Module</code> and <code>-Path</code>.</li> </ul> </li> <li>Configuration - Configuration of rules is handled by PSRule.<ul> <li>Rules can be configured at runtime, from YAML configuration, or environment variables.</li> <li>Baselines can be used to pair rules and configuration for a specific scenario.</li> </ul> </li> <li>Exceptions - Exceptions to a rule can be ignored for a single object using suppression.<ul> <li>Exclusion can be used additionally to ignore a rule entirely.</li> </ul> </li> </ul> <p>These features make PSRule ideal for validating:</p> <ul> <li>Infrastructure as code, including:<ul> <li>Kubernetes manifests.</li> <li>Azure Resource Manager (ARM) templates.</li> <li>Configuration files.</li> <li>Pipeline files.</li> </ul> </li> <li>Deployments or configurations against a baseline.</li> </ul> <p>If you want to test PowerShell code, consider using Pester, we do!</p>"},{"location":"faq/#what-pre-built-modules-are-available-for-psrule","title":"What pre-built modules are available for PSRule?","text":"<p>PSRule rules modules can be found on the PowerShell Gallery using the tag <code>PSRule-rules</code>.</p>"},{"location":"faq/#how-do-i-configure-psrule","title":"How do I configure PSRule?","text":"<p>PSRule and rules can be configured by:</p> <ul> <li>Parameter - PSRule can be configured at runtime by passing the <code>-Option</code> parameter to cmdlets.</li> <li>Options file - Options stored in YAML are load configuration from file. The default <code>ps-rule.yaml</code> option file is read automatically from the current working path by default. When checking into source control, store this file in the root directory of the repository.</li> <li>Environment variables - Configuration can be specified using environment variables.</li> </ul> <p>For example:</p> <pre><code># With cmdlet\n$option = New-PSRuleOption -OutputAs Summary -OutputCulture 'en-AU' -ExecutionUnprocessedObject 'Ignore' -Configuration @{\n  CUSTOM_VALUE = 'example'\n}\n$items | Assert-PSRule -Option $option\n\n# With hashtable\n$items | Assert-PSRule -Option @{\n  'Output.As' = 'Summary'\n  'Output.Culture' = 'en-AU'\n  'Execution.UnprocessedObject' = 'Ignore'\n  'Configuration.CUSTOM_VALUE' = 'Example'\n}\n</code></pre> <pre><code># With YAML\noutput:\n  as: Summary\n  culture: [ 'en-AU' ]\n\nexecution:\n  unprocessedObject: Ignore\n\nconfiguration:\n  CUSTOM_VALUE: Example\n</code></pre> <pre><code># With environment variable in bash\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\nexport PSRULE_OUTPUT_AS=Summary\nexport PSRULE_OUTPUT_CULTURE=en-AU\nexport PSRULE_CONFIGURATION_CUSTOM_VALUE=Example\n</code></pre> <p>For a list of configuration options and usage see about_PSRule_Options.</p>"},{"location":"faq/#how-do-i-ignore-a-rule","title":"How do I ignore a rule?","text":"<p>To prevent a rule executing you can either:</p> <ul> <li>Exclude the rule - The rule is not executed for any object.</li> <li>Suppress the rule - The rule is not executed for a specific object by name.</li> </ul> <p>To exclude a rule use the <code>Rule.Exclude</code> option. To do this in YAML, add the following to the <code>ps-rule.yaml</code> options file.</p> <pre><code># YAML: Using the rule/exclude property\nrule:\n  exclude:\n  - 'My.FirstRule'  # The name of the first rule to exclude.\n  - 'My.SecondRule' # The name of the second rule to exclude.\n</code></pre> <p>To suppress a rule use the <code>Suppression</code> option. To do this in YAML, add the following to the <code>ps-rule.yaml</code> options file.</p> <pre><code># YAML: Using the suppression property\nsuppression:\n  My.FirstRule:    # The name of the rule being suppressed\n  - TestObject1    # The name of the first object to suppress\n  - TestObject3    # The name of the second object to suppress\n  My.SecondRule:   # An additional rule to suppress\n  - TestObject2\n</code></pre> <p>The name of the object is reported by PSRule in output results.</p> <p>See about_PSRule_Options for additional usage for both of these options.</p>"},{"location":"faq/#how-do-exclude-or-ignore-files-from-being-processed","title":"How do exclude or ignore files from being processed?","text":"<p>To exclude or ignore files from being processed, configure the Input.PathIgnore option. This option allows you to ignore files using a path spec.</p> <p>For example:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude files with these extensions\n  - '*.md'\n  - '*.png'\n  # Exclude specific configuration files\n  - 'bicepconfig.json'\n</code></pre> <p>Or:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude all files\n  - '*'\n  # Only process deploy.bicep files\n  - '!**/deploy.bicep'\n</code></pre>"},{"location":"faq/#how-do-i-disable-or-suppress-the-not-processed-warning","title":"How do I disable or suppress the not processed warning?","text":"<p>You may receive a warning message suggesting a file or object has not been processed. If there are no rules that apply to the file or object this warning will be displayed.</p> <p>Note</p> <p>This warning is intended as a verification so that you are able to confirm your configuration is correct.</p> <p>After you have tuned your configuration, you may wish to disable this warning to reduce output noise. To do this you have two options:</p> <ol> <li>Exclude files from analysis \u2014 Configure the Input.PathIgnore option.</li> <li> <p>Disable the warning entirely \u2014 Set the Execution.UnprocessedObject option to <code>Ignore</code>.</p> </li> </ol>"},{"location":"faq/#how-do-i-layer-on-custom-rules-on-top-of-an-existing-module","title":"How do I layer on custom rules on top of an existing module?","text":"<p>PSRule allows rules from modules and standalone (loose) rules to be run together.</p> <p>To run rules from a standalone path use:</p> <pre><code># Note: .ps-rule/ is a standard path to include standalone rules.\n\n# With input from the pipeline\n$items | Assert-PSRule -Path '.ps-rule/'\n\n# With input from file\nAssert-PSRule -Path '.ps-rule/' -InputPath 'src/'\n</code></pre> <p>To run rules from an installed module use:</p> <pre><code># With input from the pipeline\n$items | Assert-PSRule -Module 'PSRule.Rules.Azure'\n\n# With input from file\nAssert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'src/'\n</code></pre> <p>Combining both:</p> <pre><code>Assert-PSRule -Module 'PSRule.Rules.Azure', 'PSRule.Rules.CAF' -Path '.ps-rule/' -InputPath 'src/'\n</code></pre>"},{"location":"faq/#why-should-i-use-psrule-keywords-and-assertions","title":"Why should I use PSRule keywords and assertions?","text":"<p>Except for the <code>Rule</code> keyword, using the built-in language features are optional.</p> <p>The built-in keywords and assertions accelerate rule creation. They do this by providing a condition and a set of reasons in a single command.</p> <p>Reasons are also optional; however, they provide additional context as to why the rule failed. Alternatively, you can provide your own reasons to complement standard PowerShell with the <code>Reason</code> keyword.</p>"},{"location":"faq/#collection-of-telemetry","title":"Collection of telemetry","text":"<p>PSRule currently does not collect any telemetry during installation or execution.</p> <p>PowerShell (used by PSRule) does collect basic telemetry by default. Collection of telemetry in PowerShell and how to opt-out is explained in about_Telemetry.</p>"},{"location":"features/","title":"Features","text":""},{"location":"features/#devops","title":"DevOps","text":"<p>PSRule allows you to quickly plug-in Infrastructure as Code (IaC) controls into your DevOps pipeline.</p> <ul> <li>Shift-left \u2014 Identify configuration issues and provide fast feedback in PRs.</li> <li>Quality gates \u2014 Implement quality gates between environments such as dev, test, and prod.</li> <li>Monitor continuously \u2014 Perform ongoing checks for configuration optimization opportunities.</li> </ul> <p>Run on MacOS, Linux, and Windows or anywhere PowerShell is supported. Native support for popular continuous integration (CI) systems includes:</p> <ul> <li>GitHub Actions \u2014 Trigger tests for GitHub repositories using workflows.</li> <li>Azure Pipelines \u2014 Use tasks to run tests in Azure DevOps YAML or Classic pipelines and releases.</li> </ul>"},{"location":"features/#extensible","title":"Extensible","text":"<p>Import pre-built rules or define your own using YAML, JSON, or PowerShell format. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.</p> <ul> <li>YAML \u2014 Use a popular, easy to read, and learn IaC format.   With YAML, you can quickly build out common rules with minimal effort and no scripting experience.</li> <li>JSON \u2014 Is ubiquitous, used by many tools.   While this format is typically harder to read then YAML it is easy to automate.   You may prefer to use this format if you are generating rules with automation.</li> <li>PowerShell \u2014 Is a flexible scripting language.   If you or your team already can write a basic PowerShell script, you can already define a rule.   PowerShell allows you to tap into a large world-wide community of PowerShell users.   Use existing cmdlets to help you build out rules quickly.</li> </ul> <p>Rules can be authored using any text editor, but we provide a native extension for Visual Studio Code. Use the extension to quickly author rules or run tests locally before you commit your IaC.</p>"},{"location":"features/#reusable","title":"Reusable","text":"<p>Typically unit tests in traditional testing frameworks are written for a specific case. This makes it hard invest in tests that are not easily reusable between projects. Several features of PSRule make it easier to reuse and share rules across teams or organizations.</p> <p>The following built-in features improve portability:</p> <ul> <li>Modular \u2014 Rules can be packages up into a standard PowerShell module then distributed.<ul> <li>Private \u2014 Modules can be published privately on a network share or NuGet feed.</li> <li>Public \u2014 Distribute rules globally using the PowerShell Gallery.</li> </ul> </li> <li>Configuration \u2014 PSRule and rules can be configured.</li> <li>Baselines \u2014 An artifact containing rules and configuration for a scenario.</li> <li>Suppression \u2014 Allows you to handle and keep exceptions auditable in git history.<ul> <li>Approval \u2014 Use code owners and branch policy concepts to control changes.</li> </ul> </li> <li> <p>Documentation \u2014 Provide guidance on how to resolve detected issues.</p> <ul> <li>Quick \u2014 Use a one liner to quickly add a hint or reference on rules you build.</li> <li>Detailed \u2014 Support for markdown allows you to provide detailed detailed guidance to resolve issues.</li> </ul> </li> </ul>"},{"location":"install/","title":"Install PSRule","text":"<p>PSRule supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates.</p> Task Options Run tests within CI pipelines With GitHub Actions or Azure Pipelines or CLI or PowerShell Run tests locally during development With Visual Studio Code and CLI / PowerShell Create custom tests for your organization With Visual Studio Code and CLI / PowerShell <p>Tip</p> <p>PSRule provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines. If you are using a different CI system you can use the local install to run on MacOS, Linux, and Windows worker nodes.</p>"},{"location":"install/#with-github-actions","title":"With GitHub Actions","text":"<p> GitHub Action</p> <p>Install and use PSRule with GitHub Actions by referencing the <code>microsoft/ps-rule</code> action.</p> Specific versionLatest stable v2Latest stable GitHub Actions<pre><code>- name: Analyze with PSRule\n  uses: microsoft/ps-rule@v2.9.0\n</code></pre> GitHub Actions<pre><code>- name: Analyze with PSRule\n  uses: microsoft/ps-rule@v2\n</code></pre> GitHub Actions<pre><code>- name: Analyze with PSRule\n  uses: microsoft/ps-rule@latest\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p> <p>Tip</p> <p>The recommended approach is to pin to the latest specific version. Pinning to a specific version reduces the risk of new versions breaking your pipeline. You can easily update to the latest version by changing the version number. At such time, you can test the new version in a feature branch before merging to main.</p>"},{"location":"install/#working-with-dependabot","title":"Working with Dependabot","text":"<p>You can use Dependabot to automatically upgrade your PSRule action if you use a specific version. When new versions a released Dependabot will automatically add a pull request (PR) for you to review and merge.</p> .github/dependabot.yaml<pre><code>#\n# Dependabot configuration\n#\nversion: 2\nupdates:\n\n  # Maintain GitHub Actions\n  - package-ecosystem: github-actions\n    directory: \"/\"\n    schedule:\n      interval: daily\n</code></pre>"},{"location":"install/#with-azure-pipelines","title":"With Azure Pipelines","text":"<p> Extension</p> <p>Install and use PSRule with Azure Pipeline by using extension tasks. Install the extension from the marketplace, then use the <code>ps-rule-assert</code> task in pipeline steps.</p> <pre><code>- task: ps-rule-assert@2\n  displayName: Analyze Azure template files\n  inputs:\n    inputType: repository\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p>"},{"location":"install/#with-visual-studio-code","title":"With Visual Studio Code","text":"<p> Extension</p> <p>An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in tasks and configuration schemas for working with PSRule.</p> <p> </p>"},{"location":"install/#with-cli","title":"With CLI","text":"<p>PSRule can be installed from NuGet.org using the .NET CLI where the .NET 8.0 SDK is available. You can use this option to install on CI workers that are not natively supported.</p> <p>To install PSRule as a global tool use the following command line:</p> <pre><code>dotnet tool install -g Microsoft.PSRule.Tool\n</code></pre> <p>To install a specific version use the following command line:</p> <pre><code>dotnet tool install -g Microsoft.PSRule.Tool --version 3.0.0-B0151\n</code></pre> <p>For a list of commands supported by the CLI, see PSRule CLI.</p>"},{"location":"install/#with-powershell","title":"With PowerShell","text":"<p>PSRule can be installed locally from the PowerShell Gallery using PowerShell. You can use this option to install on CI workers that are not natively supported.</p>"},{"location":"install/#prerequisites","title":"Prerequisites","text":"Operating System Tool Installation Link Windows Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater. link Windows, MacOS, Linux PowerShell version 7.4.x or greater. link <p>Note</p> <p>If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.</p>"},{"location":"install/#installing-powershell","title":"Installing PowerShell","text":"<p>PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default. For a list of platforms that PowerShell 7.4 is supported on and install instructions see Get PowerShell.</p>"},{"location":"install/#getting-the-modules","title":"Getting the modules","text":"<p> Module</p> <p>PSRule can be installed or updated from the PowerShell Gallery. Use the following command line examples from a PowerShell terminal to install or update PSRule.</p> For the current userFor all users <p>To install PSRule for the current user use:</p> <pre><code>Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\n</code></pre> <p>To update PSRule for the current user use:</p> <pre><code>Update-Module -Name 'PSRule' -Scope CurrentUser\n</code></pre> <p>Open PowerShell with Run as administrator on Windows or <code>sudo pwsh</code> on Linux.</p> <p>To install PSRule for all users (requires admin/ root permissions) use:</p> <pre><code>Install-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers\n</code></pre> <p>To update PSRule for all users (requires admin/ root permissions) use:</p> <pre><code>Update-Module -Name 'PSRule' -Scope AllUsers\n</code></pre>"},{"location":"install/#pre-release-versions","title":"Pre-release versions","text":"<p>To use a pre-release version of PSRule add the <code>-AllowPrerelease</code> switch when calling <code>Install-Module</code>, <code>Update-Module</code>, or <code>Save-Module</code> cmdlets.</p> <p>Tip</p> <p>To install pre-release module versions, the latest version of PowerShellGet may be required.</p> <pre><code># Install the latest PowerShellGet version\nInstall-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\n</code></pre> For the current userFor all users <p>To install PSRule for the current user use:</p> <pre><code>Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser -AllowPrerelease\n</code></pre> <p>Open PowerShell with Run as administrator on Windows or <code>sudo pwsh</code> on Linux.</p> <p>To install PSRule for all users (requires admin/ root permissions) use:</p> <pre><code>Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers -AllowPrerelease\n</code></pre>"},{"location":"install/#building-from-source","title":"Building from source","text":"<p> Source</p> <p>PSRule is provided as open source on GitHub. To build PSRule from source code:</p> <ol> <li>Clone the GitHub repository.</li> <li>Run <code>./build.ps1</code> from a PowerShell terminal in the cloned path.</li> </ol> <p>This build script will compile the module and documentation then output the result into <code>out/modules/PSRule</code>.</p>"},{"location":"install/#development-dependencies","title":"Development dependencies","text":"<p>The following PowerShell modules will be automatically install if the required versions are not present:</p> <ul> <li>PlatyPS</li> <li>Pester</li> <li>PSScriptAnalyzer</li> <li>PowerShellGet</li> <li>PackageManagement</li> <li>InvokeBuild</li> </ul> <p>These additional modules are only required for building PSRule.</p> <p>Additionally .NET SDK v8 is required. .NET will not be automatically downloaded and installed. To download and install the latest SDK see Download .NET 8.0.</p>"},{"location":"install/#limited-access-networks","title":"Limited access networks","text":"<p>If you are on a network that does not permit Internet access to the PowerShell Gallery, download the required PowerShell modules on an alternative device that has access. PowerShell provides the <code>Save-Module</code> cmdlet that can be run from a PowerShell terminal to do this.</p> <p>The following command lines can be used to download the required modules using a PowerShell terminal. After downloading the modules, copy the module directories to devices with restricted Internet access.</p> Runtime modulesDevelopment modules <p>To save PSRule for offline use:</p> <pre><code>Save-Module -Name 'PSRule' -Path '.\\modules'\n</code></pre> <p>This will save PSRule into the <code>modules</code> sub-directory.</p> <p>To save PSRule development module dependencies for offline use:</p> <pre><code>$modules = @('PlatyPS', 'Pester', 'PSScriptAnalyzer', 'PowerShellGet',\n'PackageManagement', 'InvokeBuild')\nSave-Module -Name $modules -Repository PSGallery -Path '.\\modules';\n</code></pre> <p>This will save required developments dependencies into the <code>modules</code> sub-directory.</p> <p>Tip</p> <p>If you use additional rules modules such as PSRule for Azure you should also save these for offline use.</p> <p>Note</p> <p>If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.</p>"},{"location":"license-contributing/","title":"License and contributing","text":"<p>PSRule is licensed with an  MIT License, which means it's free to use and modify. But please check out the details.</p> <p>We  open source at Microsoft.</p> <p>In addition to our team, we hope you will think about contributing too. Here is how you can get started:</p> <ul> <li> Report issues.</li> <li> Up-vote existing issues that are important to you.</li> <li> Improve documentation.</li> <li> <p> Contribute code.</p> </li> </ul>"},{"location":"related-projects/","title":"Related projects","text":"<p>The PSRule project is distributed across multiple repositories. You can find out more by visiting each repository.</p> Name Description ps-rule GitHub continuous integration using GitHub Actions. PSRule-pipelines Azure DevOps continuous integration using Azure Pipelines. PSRule-vscode Support for running and authoring rules within Visual Studio Code. PSRule.Monitor Support for logging PSRule analysis results to Azure Monitor. PSRule.Rules.Azure Rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Azure-quickstart Sample code you can use to quickly start using PSRule for Azure. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements."},{"location":"related-projects/#community-modules","title":"Community modules","text":"<p>The following third-party modules are created, maintained, supported, and licensed by their respective authors. Before consuming these module, double check they meet your organization's support, security, and licensing expectations.</p> Author Name Description cloudyspells PSRule.Rules.AzureDevOps A suite of rules to validate Azure DevOps projects using PSRule."},{"location":"support/","title":"Support","text":"<p>This project uses GitHub Issues to track bugs and feature requests.</p> <p>Please search the existing issues before filing new issues to avoid duplicates.</p> <ul> <li>For new issues, file your bug or feature request as a new issue.</li> <li>For help, discussion, and support questions about using this project, join or start a discussion.</li> </ul>"},{"location":"support/#microsoft-support-policy","title":"Microsoft Support Policy","text":"<p>Support for this project/ product is limited to the resources listed above.</p>"},{"location":"troubleshooting/","title":"Troubleshooting","text":"<p>Abstract</p> <p>This article provides troubleshooting instructions for common errors generic to PSRule or core functionality.</p> <p>Tip</p> <p>See troubleshooting specific to PSRule for Azure for common errors when testing Azure resources using the <code>PSRule.Rules.Azure</code> module.</p>"},{"location":"troubleshooting/#custom-rules-are-not-running","title":"Custom rules are not running","text":"<p>There is a few common causes of this issue including:</p> <ul> <li>Check rule path \u2014 By default, PSRule will look for rules in the <code>.ps-rule/</code> directory.   This directory is the root for your repository or the current working path by default.   On case-sensitive file systems such as Linux, this directory name is case-sensitive.   See Storing and naming rules for more information.</li> <li>Check file name suffix \u2014 PSRule only looks for files with the <code>.Rule.ps1</code>, <code>.Rule.yaml</code>, or <code>.Rule.jsonc</code> suffix.   On case-sensitive file systems such as Linux, this file suffix is case-sensitive.   See Storing and naming rules for more information.</li> <li>Check binding configuration \u2014 PSRule uses binding to work out which property to use for a resource type.   To be able to use the <code>-Type</code> parameter or <code>type</code> properties in rules definitions, binding must be set.   This is automatically configured for modules such as PSRule for Azure, however must be set in <code>ps-rule.yaml</code> for custom rules.</li> <li>Check modules \u2014 Check if your custom rules have a dependency on another module such as <code>PSRule.Rules.Azure</code>.   If your rules have a dependency, be sure to add the module in your command-line.</li> </ul> <p>Tip</p> <p>You may be able to use <code>git mv</code> to change the case of a file if it is committed to the repository incorrectly.</p>"},{"location":"troubleshooting/#windows-powershell-is-in-noninteractive-mode","title":"Windows PowerShell is in NonInteractive mode","text":"<p>When running PSRule on a Windows self-hosted agent/ private runner you may encounter an error similar to the following:</p> <p>Error</p> <p>Exception calling \"ShouldContinue\" with \"2\" argument(s): \"Windows PowerShell is in NonInteractive mode. Read and Prompt functionality is not available.\"</p> <p>This error may be caused by the PowerShell NuGet package provider not being installed. By default, Windows PowerShell does not have these components installed. These components are required for installing and checking versions of PSRule modules.</p> <p>To resolve this issue, install the NuGet package provider during setup the agent/ runner by using the following script:</p> <pre><code>if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction Ignore)) {\n    Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\n</code></pre> <p>Additionally consider installing the latest version of <code>PowerShellGet</code> by using the following script:</p> <pre><code>if ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion 2.2.1 -ErrorAction Ignore)) {\n    Install-Module PowerShellGet -MinimumVersion 2.2.1 -Scope CurrentUser -Force -AllowClobber;\n}\n</code></pre>"},{"location":"troubleshooting/#format-default-error-when-running-invoke-psrule","title":"Format-Default error when running Invoke-PSRule","text":"<p>When running PSRule you may encounter an error similar to the following:</p> <p>Error</p> <p>Format-Default: Cannot process argument because the value of argument \"name\" is not valid. Change the value of the \"name\" argument and run the operation again.</p> <p>This error is caused by a known issue in PowerShell 7.4.0 and 7.4.1. To resolve this issue, upgrade to PowerShell 7.4.2 or later.</p> <p>For more details see #1723.</p>"},{"location":"troubleshooting/#psr0001-unable-to-read-options-file","title":"PSR0001 - Unable to read options file","text":"<p>When running PSRule you may encounter an error similar to the following:</p> <p>Error</p> <p>PSR0001: Unable to read options file 'ps-rule.yaml'.</p> <p>This error typically indicates a problem with the YAML syntax in the <code>ps-rule.yaml</code> file. Double check the file for incorrect indentation or missing punctuation such as <code>-</code> and <code>:</code> characters.</p> <p>If you still have an issue, try re-saving the file as UTF-8 in an editor such as Visual Studio Code.</p>"},{"location":"troubleshooting/#psr0002-summary-results-are-not-supported-with-job-summaries","title":"PSR0002 - Summary results are not supported with Job Summaries","text":"<p>Error</p> <p>PSR0002: Summary results are not supported with Job Summaries.</p> <p>Currently using the <code>Output.As</code> with the <code>Summary</code> option is not supported with job summaries. Choose to use one or the other.</p> <p>If you have a specific use case your would like to enable, please start a discussion.</p>"},{"location":"troubleshooting/#psr0003-the-specified-baseline-group-is-not-known","title":"PSR0003 - The specified baseline group is not known","text":"<p>Error</p> <p>PSR0003: The specified baseline group 'latest' is not known.</p> <p>This error is caused by attempting to reference a baseline group which has not been defined. To define a baseline group, see Baseline.Group option.</p>"},{"location":"troubleshooting/#psr0004-the-specified-resource-is-not-known","title":"PSR0004 - The specified resource is not known","text":"<p>Error</p> <p>PSR0004: The specified Baseline resource 'TestModule4\\Module4' is not known.</p> <p>This error is caused when you attempt to reference a resource such as a baseline, rule, or selector which has not been defined.</p>"},{"location":"upgrade-notes/","title":"Upgrade notes","text":"<p>This document contains notes to help upgrade from previous versions of PSRule.</p>"},{"location":"upgrade-notes/#upgrading-to-v300","title":"Upgrading to v3.0.0","text":""},{"location":"upgrade-notes/#unbound-object-names","title":"Unbound object names","text":"<p>When an object is processed by PSRule, it is assigned a name. This name is used to identify the object in the output and to suppress the object from future processing.</p> <p>Prior to v3.0.0, the name was generated using a SHA-1 hash of the object. The SHA-1 algorithm is no longer considered secure and has been replaced with SHA-512.</p> <p>From v3.0.0, if the name of an object can not be determined, the SHA-512 hash of the object will be used. Any objects that have previously been suppressed with a name based on a SHA-1 hash will no longer be suppressed.</p> <p>To resolve any issue caused by this change, you can:</p> <ol> <li>Configure binding by setting the Binding.TargetName option to set an alternative property to use as the name. OR</li> <li> <p>Update any existing keys set with the Suppression option to use the new SHA-512 hash.</p> </li> </ol>"},{"location":"upgrade-notes/#using-powershell-74-or-later","title":"Using PowerShell 7.4 or later","text":"<p>From v3.0.0, PSRule requires:</p> <ul> <li>Windows PowerShell 5.1 for running as a PowerShell module. OR</li> <li>PowerShell 7.4 or later for development, building locally, or running as a PowerShell module.</li> </ul> <p>Support for Windows PowerShell 5.1 is deprecated and will be removed in a future release of PSRule (v4). We recommend upgrading to PowerShell 7.4 or later.</p>"},{"location":"upgrade-notes/#changes-to-cli-commands","title":"Changes to CLI commands","text":"<p>From v3.0.0, the CLI command names have been renamed to simplify usage. The following changes have been made:</p> <ul> <li>To run rules, use <code>run</code> instead of <code>analyze</code>. i.e. <code>ps-rule run</code>.</li> <li>To restore modules for a workspace, use <code>module restore</code> instead of <code>restore</code>. i.e. <code>ps-rule module restore</code>.</li> </ul> <p>The <code>run</code> command provides similar output to the <code>Assert-PSRule</code> cmdlet in PowerShell.</p> <p>Previously the <code>restore</code> command installed modules based on the configuration of the Requires option. From v3.0.0, the <code>module restore</code> command installs modules based on:</p> <ul> <li>The module lock file <code>ps-rule.lock.json</code> if set.   Use <code>module</code> CLI commands to manage the lock file. AND</li> <li> <p>Modules defined in the Include.Module option, if set.   Additionally the Requires option is used to constrain the version of modules installed.</p> </li> </ul>"},{"location":"upgrade-notes/#upgrading-to-v200","title":"Upgrading to v2.0.0","text":""},{"location":"upgrade-notes/#resources-naming-restrictions","title":"Resources naming restrictions","text":"<p>When naming resources such as rules or selectors, the following restrictions apply:</p> <ul> <li>Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.</li> <li>Only use allowed characters \u2014   To preserve consistency between file systems, some characters are not permitted.   Dots, hyphens, and underscores are not permitted at the start and end of the name.   Additionally some characters are restricted for future use.   The following characters are not permitted:<ul> <li><code>&lt;</code> (less than)</li> <li><code>&gt;</code> (greater than)</li> <li><code>:</code> (colon)</li> <li><code>/</code> (forward slash)</li> <li><code>\\</code> (backslash)</li> <li><code>|</code> (vertical bar or pipe)</li> <li><code>?</code> (question mark)</li> <li><code>*</code> (asterisk)</li> <li><code>\"</code> (double quote)</li> <li><code>'</code> (single quote)</li> <li><code>`</code> (backtick)</li> <li><code>+</code> (plus)</li> <li><code>@</code> (at sign)</li> <li>Integer value zero, sometimes referred to as the ASCII NUL character.</li> <li>Characters whose integer representations are in the range from 1 through 31.</li> </ul> </li> </ul> <p>Prior to v2.0.0, there was no specific naming restriction for resources. However functionally PSRule and downstream components could not support all resource names. To avoid confusion, we have decided to restrict resource names to a specific set of characters.</p> <p>From v2.0.0, resource names that do not meet the naming restrictions will generate an error.</p> Regular expression for valid resource names<pre><code>^[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^&lt;&gt;:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\n</code></pre>"},{"location":"upgrade-notes/#setting-default-module-baseline","title":"Setting default module baseline","text":"<p>When packaging rules in a module, you can set the default baseline. The default baseline from the module will be automatically used unless overridden.</p> <p>Prior to v1.9.0 the default baseline was set by configuring the module manifest <code>.psd1</code> file. From v1.9.0 the default baseline can be configured by within a module configuration. Using module configuration is the recommended method. Setting the default baseline from module manifest and has been removed from v2.0.0.</p> <p>A module configuration can be defined in YAML.</p> <p>Example</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  rule:\n    baseline: Enterprise.Default\n</code></pre>"},{"location":"upgrade-notes/#setting-resource-api-version","title":"Setting resource API version","text":"<p>When creating YAML and JSON resources you define a resource by specifying the <code>apiVersion</code> and <code>kind</code>. An <code>apiVersion</code> was added as a requirement from v1.2.0. For compatibility, resources without an <code>apiVersion</code> were supported however deprecated for removal. This has now been removed from v2.0.0.</p> <p>When defining resource specify an <code>apiVersion</code>. Currently this must be set to <code>github.com/microsoft/PSRule/v1</code>.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre>"},{"location":"upgrade-notes/#change-in-source-file-discovery-for-get-psrulehelp","title":"Change in source file discovery for Get-PSRuleHelp","text":"<p>Previously in PSRule v1.11.0 and prior versions, rules would show up twice when running <code>Get-PSRuleHelp</code> in the context of a module and in the same working directory of the module. This behavior has now been removed from v2.0.0.</p> <p>Module files are now preferred over loose files, and rules are only shown once in the output. Any duplicate rule names from loose files are outputted as a warning instead.</p> <p>The old behavior:</p> <pre><code>Name                                ModuleName               Synopsis\n----                                ----------               --------\nM1.Rule1                                                     This is the default\nM1.Rule2                                                     This is the default\nM1.Rule1                            TestModule               Synopsis en-AU.\nM1.Rule2                            TestModule               This is the default\n</code></pre> <p>The new behavior:</p> <pre><code>WARNING: A rule with the same name 'M1.Rule1' already exists.\nWARNING: A rule with the same name 'M1.Rule2' already exists.\n\nName                                ModuleName               Synopsis\n----                                ----------               --------\nM1.Rule1                            TestModule               Synopsis en-AU.\nM1.Rule2                            TestModule               This is the default\n</code></pre>"},{"location":"upgrade-notes/#require-source-discovery-from-current-working-directory-to-be-explicitly-included","title":"Require source discovery from current working directory to be explicitly included","text":"<p>Previously in PSRule v1.11.0 and prior versions, rule sources from the current working directory without the <code>-Path</code> and <code>-Module</code> parameters were automatically included. This behavior has now been removed from v2.0.0.</p> <p>Rules sources in the current working directory are only included if <code>-Path .</code> or <code>-Path $PWD</code> is specified.</p> <p>The old behavior:</p> PowerShell<pre><code>Set-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\nRuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nappServicePlan.MinInstanceCount                                App Service Plan has multiple instances\nappServicePlan.MinPlan                                         Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity                                      Disable client affinity for stateless services\nappServiceApp.UseHTTPS                                         Use HTTPS only\nstorageAccounts.UseHttps                                       Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption                                  Use at-rest storage encryption\n</code></pre> <p>The new behavior:</p> PowerShell<pre><code>Set-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\n# No output, need to specify -Path explicitly\n\nGet-PSRule -Path $PWD\n\nRuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nappServicePlan.MinInstanceCount                                App Service Plan has multiple instances\nappServicePlan.MinPlan                                         Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity                                      Disable client affinity for stateless services\nappServiceApp.UseHTTPS                                         Use HTTPS only\nstorageAccounts.UseHttps                                       Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption      \n</code></pre>"},{"location":"upgrade-notes/#upgrading-to-v140","title":"Upgrading to v1.4.0","text":"<p>Follow these notes to upgrade to PSRule v1.4.0 from previous versions.</p>"},{"location":"upgrade-notes/#change-in-default-output-styles","title":"Change in default output styles","text":"<p>Previously in PSRule v1.3.0 and prior the default style when using <code>Assert-PSRule</code> was <code>Client</code>. From v1.4.0 PSRule now defaults to <code>Detect</code>.</p> <p>The <code>Detect</code> output style falls back to <code>Client</code> however may detect one of the following styles instead:</p> <ul> <li><code>AzurePipelines</code> - Output is written for integration Azure Pipelines.</li> <li><code>GitHubActions</code> - Output is written for integration GitHub Actions.</li> <li><code>VisualStudioCode</code> - Output is written for integration with Visual Studio Code.</li> </ul> <p>Detect uses the following logic:</p> <ol> <li>If the <code>TF_BUILD</code> environment variable is set to <code>true</code>, <code>AzurePipelines</code> will be used.</li> <li>If the <code>GITHUB_ACTIONS</code> environment variable is set to <code>true</code>, <code>GitHubActions</code> will be used.</li> <li>If the <code>TERM_PROGRAM</code> environment variable is set to <code>vscode</code>, <code>VisualStudioCode</code> will be used.</li> <li>Use <code>Client</code>.</li> </ol> <p>To force usage of the <code>Client</code> output style set the <code>Output.Style</code> option. For example:</p> ps-rule.yaml<pre><code># YAML: Using the output/style property\noutput:\n  style: Client\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=Client\n</code></pre> GitHub Actions<pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_STYLE: Client\n</code></pre> Azure Pipelines<pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n  value: Client\n</code></pre>"},{"location":"upgrade-notes/#upgrading-to-v100","title":"Upgrading to v1.0.0","text":"<p>Follow these notes to upgrade to PSRule v1.0.0 from previous versions.</p>"},{"location":"upgrade-notes/#replaced-rule-target-properties","title":"Replaced $Rule target properties","text":"<p>Previously in PSRule v0.22.0 and prior the <code>$Rule</code> automatic variable had the following properties:</p> <ul> <li><code>TargetName</code></li> <li><code>TargetType</code></li> <li><code>TargetObject</code></li> </ul> <p>For example:</p> PowerShell rules<pre><code>Rule 'Rule1' {\n    $Rule.TargetName -eq 'Name1';\n    $Rule.TargetType -eq '.json';\n    $Rule.TargetObject.someProperty -eq 1;\n}\n</code></pre> <p>In v1.0.0 these properties have been removed after being deprecated in v0.12.0. These properties are instead available on the <code>$PSRule</code> variable. Rules referencing the deprecated properties of <code>$Rule</code> must be updated.</p> <p>For example:</p> PowerShell rules<pre><code>Rule 'Rule1' {\n    $PSRule.TargetName -eq 'Name1';\n    $PSRule.TargetType -eq '.json';\n    $PSRule.TargetObject.someProperty -eq 1;\n}\n</code></pre>"},{"location":"validating-locally/","title":"Validating locally","text":"<p>PSRule can be installed locally on MacOS, Linux, and Windows for local validation. This allows you to test Infrastructure as Code (IaC) artifacts before pushing changes to a repository.</p> <p>Tip</p> <p>If you haven't already, follow the instructions on installing locally before continuing.</p>"},{"location":"validating-locally/#with-visual-studio-code","title":"With Visual Studio Code","text":"<p> Extension</p> <p>An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in task PSRule: Run analysis task.</p> <p> </p> <p>Info</p> <p>To learn about tasks in Visual Studio Code see Integrate with External Tools via Tasks.</p>"},{"location":"validating-locally/#customizing-the-task","title":"Customizing the task","text":"<p>The PSRule: Run analysis task will be available automatically after you install the PSRule extension. You can customize the defaults of the task by editing or inserting the task into <code>.vscode/tasks.json</code> within your workspace.</p> JSON<pre><code>{\n    \"type\": \"PSRule\",\n    \"problemMatcher\": [\n        \"$PSRule\"\n    ],\n    \"label\": \"PSRule: Run analysis\",\n    \"modules\": [\n        \"PSRule.Rules.Azure\"\n    ],\n    \"presentation\": {\n        \"clear\": true,\n        \"panel\": \"dedicated\"\n    }\n}\n</code></pre> <p>Example</p> <p>A complete <code>.vscode/tasks.json</code> might look like the following:</p> .vscode/tasks.json<pre><code>{\n    \"version\": \"2.0.0\",\n    \"tasks\": [\n        {\n            \"type\": \"PSRule\",\n            \"problemMatcher\": [\n                \"$PSRule\"\n            ],\n            \"label\": \"PSRule: Run analysis\",\n            \"modules\": [\n                \"PSRule.Rules.Azure\"\n            ],\n            \"presentation\": {\n                \"clear\": true,\n                \"panel\": \"dedicated\"\n            }\n        }\n    ]\n}\n</code></pre>"},{"location":"versioning/","title":"Changes and versioning","text":"<p>PSRule uses semantic versioning to declare breaking changes. The latest module version can be installed from the PowerShell Gallery. For a list of module changes please see the change log.</p>"},{"location":"versioning/#pre-releases","title":"Pre-releases","text":"<p>Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Module versions and change log details for pre-releases will be removed as stable releases are made available.</p> <p>Important</p> <p>Pre-release versions should be considered work in progress. These releases should not be used in production. We may introduce breaking changes between a pre-release as we work towards a stable version release.</p>"},{"location":"versioning/#experimental-features","title":"Experimental features","text":"<p>From time to time we may ship experiential features. These features are generally marked experiential in the change log as these features ship. Experimental features may ship in stable releases, however to use them you may need to:</p> <ul> <li>Enable or explicitly reference them.</li> </ul> <p>Important</p> <p>Experimental features should be considered work in progress. These features may be incomplete and should not be used in production. We may introduce breaking changes for experimental features as we work towards a general release for the feature.</p>"},{"location":"versioning/#reporting-bugs","title":"Reporting bugs","text":"<p>If you experience an issue with an pre-release or experimental feature please let us know by logging an issue as a bug.</p>"},{"location":"authoring/packaging-rules/","title":"Packaging rules in a module","text":"<p>PSRule supports distribution of rules within modules. Using a module, rules can be published and installed using standard PowerShell cmdlets.</p> <p>You should consider packaging rules into a module to:</p> <ul> <li>Version rules. PowerShell modules support semantic versioning (semver).</li> <li>Reuse rules across projects, pipelines or teams.</li> <li>Publish rules to external consumers via the PowerShell Gallery.</li> </ul> <p>This scenario covers the following:</p> <ul> <li>Creating a module manifest</li> <li>Including rules and baselines</li> <li>Defining a module configuration</li> <li>Including documentation</li> </ul>"},{"location":"authoring/packaging-rules/#creating-a-module-manifest","title":"Creating a module manifest","text":"<p>When creating a PowerShell module, a module manifest is an optional file that stores module metadata. Module manifests use the <code>.psd1</code> file extension. When packaging rules in a module, a module manifest is required for PSRule discover the module.</p>"},{"location":"authoring/packaging-rules/#creating-the-manifest-file","title":"Creating the manifest file","text":"<p>A module manifest can be created from PowerShell using the <code>New-ModuleManifest</code> cmdlet. Additionally, Visual Studio Code and many other tools also include snippets for creating a module manifest.</p> <p>For example:</p> <pre><code># Create a directory for the module\nmd ./Enterprise.Rules;\n\n# Create the manifest\nNew-ModuleManifest -Path ./Enterprise.Rules/Enterprise.Rules.psd1 -Tags 'PSRule-rules';\n</code></pre> <p>The example above creates a module manifest for a module named Enterprise.Rules tagged with <code>PSRule-rules</code>. The use of the <code>PSRule-rules</code> tag is explained in the following section.</p>"},{"location":"authoring/packaging-rules/#setting-module-tags","title":"Setting module tags","text":"<p>When PSRule cmdlets are used with the <code>-Module</code> parameter, PSRule discovers rule modules. If the module is already imported, that module is used. If the module is not imported, PSRule will import the highest version of the module automatically.</p> <p>For a module to be discovered by PSRule, tag the module with <code>PSRule-rules</code>. To tag modules, find the <code>Tags</code> section the <code>PSData</code> hashtable in the module manifest and add <code>PSRule-rules</code>.</p> <p>An updated module manifest may look like this:</p> <pre><code># Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.\nPrivateData = @{\n    PSData = @{\n        # Tags applied to this module. These help with module discovery in online galleries.\n        Tags = @('PSRule-rules')\n    }\n}\n</code></pre>"},{"location":"authoring/packaging-rules/#including-rules-and-baselines","title":"Including rules and baselines","text":"<p>Rules and baselines can be included anywhere within the module directory structure. Such as in the root directory of the module or in a nested sub-directory.</p> <p>By convention, consider including rules and baselines within a <code>rules</code> sub-directory within the module.</p> <p>For example:</p> <ul> <li>Enterprise.Rules/<ul> <li>rules/<ul> <li>Baseline.Rule.yaml</li> <li>Config.Rule.yaml</li> <li>Standards.Rule.ps1</li> </ul> </li> <li>Enterprise.Rules.psd1</li> </ul> </li> </ul>"},{"location":"authoring/packaging-rules/#file-names","title":"File names","text":"<p>For PSRule to find rules included in a module, rule file names must end with the <code>.Rule.ps1</code> suffix. We recommend using the exact case <code>.Rule.ps1</code>. This is because some file systems are case-sensitive. For example, on Linux <code>Standards.rule.ps1</code> would be ignored by PSRule.</p> <p>Similarly, when including baselines within a module use the <code>.Rule.yaml</code> suffix.</p>"},{"location":"authoring/packaging-rules/#defining-a-module-configuration","title":"Defining a module configuration","text":"<p>A module configuration that sets options defaults and can be optionally packaged with a module. To set a module configuration, define a <code>ModuleConfig</code> resource within an included <code>.Rule.yaml</code> file. A module configuration <code>.Rule.yaml</code> file must be distributed within the module directory structure.</p> <p>PSRule only supports a single <code>ModuleConfig</code> resource. The name of the <code>ModuleConfig</code> must match the name of the module. Additional <code>ModuleConfig</code> resources or with an alternative name are ignored. PSRule does not support module configurations distributed outside of a module.</p> <p>Example</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  binding:\n    targetName:\n    - ResourceName\n    - FullName\n    - name\n    targetType:\n    - ResourceType\n    - type\n    - Extension\n    field:\n      resourceId: [ 'ResourceId' ]\n      subscriptionId: [ 'SubscriptionId' ]\n      resourceGroupName: [ 'ResourceGroupName' ]\n  rule:\n    baseline: Enterprise.Default\n</code></pre> <p>The following options are allowed within a <code>ModuleConfig</code>:</p> <ul> <li><code>Binding.Field</code></li> <li><code>Binding.IgnoreCase</code></li> <li><code>Binding.NameSeparator</code></li> <li><code>Binding.PreferTargetInfo</code></li> <li><code>Binding.TargetName</code></li> <li><code>Binding.TargetType</code></li> <li><code>Binding.UseQualifiedName</code></li> <li><code>Configuration</code></li> <li><code>Output.Culture</code></li> <li><code>Rule.Baseline</code></li> </ul>"},{"location":"authoring/packaging-rules/#setting-a-default-baseline","title":"Setting a default baseline","text":"<p>Optionally, baselines can be included in rule modules. If a baseline contains configuration or binding options then setting a default baseline is often desirable. When a default baseline is set, PSRule will use the named baseline automatically when processing rules from that module. This feature removes the need for users to specify it manually.</p> <p>To set a default baseline, set the <code>Rule.Baseline</code> property of the <code>ModuleConfig</code> resource.</p> <p>Example</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  binding:\n    targetName:\n    - ResourceName\n    - FullName\n    - name\n    targetType:\n    - ResourceType\n    - type\n    - Extension\n    field:\n      resourceId: [ 'ResourceId' ]\n      subscriptionId: [ 'SubscriptionId' ]\n      resourceGroupName: [ 'ResourceGroupName' ]\n  rule:\n    baseline: Enterprise.Default\n</code></pre> <p>This examples set the default baseline to <code>Enterprise.Default</code>. The default baseline must be included in file ending with <code>.Rule.yaml</code> within the module directory structure.</p>"},{"location":"authoring/packaging-rules/#including-documentation","title":"Including documentation","text":"<p>PSRule supports write and packaging rule modules with markdown documentation. Markdown documentation is automatically interpreted by PSRule and included in output.</p> <p>When including markdown, files are copied into a directory structure based on the target culture.</p> <p>For example, store documentation targeted to the culture <code>en-US</code> in a directory named <code>en-US</code>. Similarly, documentation for cultures such as <code>en-AU</code>, <code>en-GB</code> and <code>fr-FR</code> would be in separate directories.</p> <p>If a directory for the exact culture <code>en-US</code> doesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory named <code>en</code>.</p> <p>When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux <code>en-us</code> would not match.</p> <p>For example:</p> <ul> <li>Enterprise.Rules/<ul> <li>en/<ul> <li>Org.Az.Storage.UseHttps.md</li> <li>Org.Az.Resource.Tagging.md</li> </ul> </li> <li>en-US/<ul> <li>Org.Az.Storage.UseHttps.md</li> </ul> </li> <li>fr-FR/<ul> <li>Org.Az.Storage.UseHttps.md</li> </ul> </li> <li>rules/<ul> <li>Baseline.Rule.yaml</li> <li>Config.Rule.yaml</li> <li>Standards.Rule.ps1</li> </ul> </li> <li>Enterprise.Rules.psd1</li> </ul> </li> </ul>"},{"location":"authoring/packaging-rules/#more-information","title":"More information","text":"<ul> <li>Enterprise.Rules.psd1 - An example module manifest.</li> <li>Baseline.Rule.yaml - An example baseline.</li> <li>Config.Rule.yaml - An example module configuration.</li> </ul>"},{"location":"authoring/storing-rules/","title":"Storing and naming rules","text":"<p>Rules are stored in one or more files and each file can contain one or many rules. Additionally, rules can be grouped into a module and distributed.</p> <p>Abstract</p> <p>This topic covers recommendations for naming and storing rules.</p>"},{"location":"authoring/storing-rules/#using-a-standard-file-path","title":"Using a standard file path","text":"<p>Rules can be standalone or packaged within a module. Standalone rules are ideal for a single project such as an Infrastructure as Code (IaC) repository. To reuse rules across multiple projects consider packaging these as a module.</p> <p>The instructions for packaging rules in a module can be found here:</p> <ul> <li>Packaging rules in a module</li> </ul> <p>To store standalone rules we recommend that you:</p> <ul> <li>Use .ps-rule/ \u2014 Create a sub-directory called <code>.ps-rule</code> in the root of your repository.   Use all lower-case in the sub-directory name.   Put any custom rules within this sub-directory.</li> <li>Use files ending with .Rule.* \u2014 PSRule uses a file naming convention to discover rules.   Use one of the following depending on the file format you are using:<ul> <li>YAML - <code>.Rule.yaml</code>.</li> <li>JSON - <code>.Rule.jsonc</code> or <code>.Rule.json</code>.</li> <li>PowerShell - <code>.Rule.ps1</code>.</li> </ul> </li> </ul> <p>Note</p> <p>Build pipelines are often case-sensitive or run on Linux-based systems. Using the casing rule above reduces confusion latter when you configure continuous integration (CI).</p>"},{"location":"authoring/storing-rules/#naming-rules","title":"Naming rules","text":"<p>When running PSRule, rule names must be unique. For example, PSRule for Azure uses the name prefix of <code>Azure.</code> for rules included in the module.</p> <p>Example</p> <p>The following names are examples of rules included within PSRule for Azure:</p> <ul> <li><code>Azure.AKS.Version</code></li> <li><code>Azure.AKS.AuthorizedIPs</code></li> <li><code>Azure.SQL.MinTLS</code></li> </ul> <p>In addition, names for rules and other resources must meet the following requirements:</p> <ul> <li>Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.</li> <li>Only use allowed characters \u2014   To preserve consistency between file systems, some characters are not permitted.   Dots, hyphens, and underscores are not permitted at the start and end of the name.   Additionally some characters are restricted for future use.   The following characters are not permitted:<ul> <li><code>&lt;</code> (less than)</li> <li><code>&gt;</code> (greater than)</li> <li><code>:</code> (colon)</li> <li><code>/</code> (forward slash)</li> <li><code>\\</code> (backslash)</li> <li><code>|</code> (vertical bar or pipe)</li> <li><code>?</code> (question mark)</li> <li><code>*</code> (asterisk)</li> <li><code>\"</code> (double quote)</li> <li><code>'</code> (single quote)</li> <li><code>`</code> (backtick)</li> <li><code>+</code> (plus)</li> <li><code>@</code> (at sign)</li> <li>Integer value zero, sometimes referred to as the ASCII NUL character.</li> <li>Characters whose integer representations are in the range from 1 through 31.</li> </ul> </li> </ul> Regular expression for valid resource names<pre><code>^[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^&lt;&gt;:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\n</code></pre> <p>When naming rules we recommend that you:</p> <ul> <li>Use a standard prefix \u2014 You can use the <code>Local.</code> or <code>Org.</code> prefix for standalone rules.<ul> <li>Alternatively choose a short prefix that identifies your organization.</li> </ul> </li> <li>Use dotted notation \u2014 Use dots to separate rule name.</li> <li>Use a maximum length of 35 characters \u2014   The default view of <code>Invoke-PSRule</code> truncates longer names.   PSRule supports longer rule names however if <code>Invoke-PSRule</code> is called directly consider using <code>Format-List</code>.</li> <li> <p>Avoid using special characters and punctuation \u2014   Although these characters can be used in many cases, they may not be easy to use with all PSRule features.</p> </li> </ul>"},{"location":"authoring/testing-infrastructure/","title":"Testing infrastructure","text":"<p>You can use PSRule to create tests for Infrastructure as Code (IaC). Each test is called a rule.</p> <p>PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.</p> <p>Abstract</p> <p>This topic covers how to create a rule using YAML, JSON, and PowerShell by example. This example, while fictitious is indicative of common testing and validation scenarios for IaC.</p>"},{"location":"authoring/testing-infrastructure/#sample-data","title":"Sample data","text":"<p>To get started authoring a rule, we will be working with a sample file <code>settings.json</code>. This sample configuration file configures an application.</p> <p>For the purpose of this example, one configuration setting <code>supportsHttpsTrafficOnly</code> is set. This configuration setting can be either <code>true</code> or <code>false</code>. When set to <code>true</code>, Transport Layer Security (TLS) is enforced. When set to <code>false</code>, the application permits insecure communication with HTTP.</p> <p>Contents of <code>settings.json</code></p> <p>Create a <code>settings.json</code> file in the root of your repository with the following contents.</p> <pre><code>{\n    \"type\": \"app1\",\n    \"version\": 1,\n    \"configure\": {\n        \"supportsHttpsTrafficOnly\": false\n    }\n}\n</code></pre>"},{"location":"authoring/testing-infrastructure/#define-a-rule","title":"Define a rule","text":"<p>To meet the requirements of our organization we want to write a rule to:</p> <ul> <li>Enforce secure traffic by requiring <code>supportsHttpsTrafficOnly</code> to be <code>true</code>.</li> <li>Enforce use of TLS 1.2 as a minimum by requiring <code>minTLSVersion</code> to be <code>1.2</code>.</li> </ul> <p>In this section the same rule will be authored using YAML, JSON, and PowerShell.</p> <p>Tip</p> <p>To make you editing experience even better, consider installing the Visual Studio Code extension.</p> YAMLJSONPowerShell <p>Create a <code>.ps-rule/Local.Rule.yaml</code> file in your repository with the following contents.</p> <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test <code>settings.json</code>.     Specifically, the object path <code>configures.supportsHttpsTrafficOnly</code> must exist and be set to <code>true</code>.</li> </ol> <p>Create a <code>.ps-rule/Local.Rule.jsonc</code> file in your repository with the following contents.</p> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test <code>settings.json</code>.     Specifically, the object path <code>configures.supportsHttpsTrafficOnly</code> must exist and be set to <code>true</code>.</li> </ol> <p>Create a <code>.ps-rule/Local.Rule.ps1</code> file in your repository with the following contents.</p> <pre><code># Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n    $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n}\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name.</li> <li>The condition contained within the curly braces <code>{ }</code> determines the checks PSRule will use to test <code>settings.json</code>.</li> <li>The <code>$Assert.HasFieldValue</code> method checks the object path <code>configures.supportsHttpsTrafficOnly</code> exists and is set to <code>true</code>.</li> </ol> <p>Tip</p> <p>To learn more about recommended file and naming conventions for rules, continue reading Storing and naming rules.</p>"},{"location":"authoring/testing-infrastructure/#using-multiple-conditions","title":"Using multiple conditions","text":"<p>Each rule must have at least one condition. Additional conditions can be combined to check multiple test cases.</p> <p>In the example a <code>minTLSVersion</code> configuration setting does not exist and is not set.</p> YAMLJSONPowerShell <p>Update <code>.ps-rule/Local.Rule.yaml</code> in your repository with the following contents.</p> <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    allOf:\n    - field: 'configure.supportsHttpsTrafficOnly'\n      equals: true\n    - field: 'configure.minTLSVersion'\n      equals: '1.2'\n</code></pre> <ol> <li>Using the <code>allOf</code> expression requires that all conditions be true for the rule to pass.     This expression allows an array of one or more conditions to be provided.     Using <code>anyOf</code> would pass the rule if any single condition is true.</li> </ol> <p>Update <code>.ps-rule/Local.Rule.jsonc</code> in your repository with the following contents.</p> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"allOf\": [\n                    {\n                        \"field\": \"configure.supportsHttpsTrafficOnly\",\n                        \"equals\": true\n                    },\n                    {\n                        \"field\": \"configure.minTLSVersion\",\n                        \"equals\": \"1.2\"\n                    }\n                ]\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Using the <code>allOf</code> expression requires that all conditions be true for the rule to pass.     This expression allows an array of one or more conditions to be provided.     Using <code>anyOf</code> would pass the rule if any single condition is true.</li> </ol> <p>Update <code>.ps-rule/Local.Rule.ps1</code> in your repository with the following contents.</p> <pre><code># Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n    $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n    $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\n</code></pre> <ol> <li>An additional, <code>$Assert.HasFieldValue</code> assertion helper method can be called.     The rule will pass if all of the conditions return true.</li> </ol>"},{"location":"authoring/testing-infrastructure/#testing","title":"Testing","text":""},{"location":"authoring/testing-infrastructure/#testing-manually","title":"Testing manually","text":"<p>To test the rule manually, run the following command.</p> <pre><code>Assert-PSRule -f ./settings.json\n</code></pre>"},{"location":"authoring/testing-infrastructure/#advanced-usage","title":"Advanced usage","text":""},{"location":"authoring/testing-infrastructure/#severity-level","title":"Severity level","text":"<p> v2.0.0</p> <p>When defining a rule, you can specify a severity level. The severity level is used if the rule fails. By default, the severity level for a rule is <code>Error</code>.</p> <ul> <li><code>Error</code> - A serious problem that must be addressed before going forward.</li> <li><code>Warning</code> - A problem that should be addressed.</li> <li><code>Information</code> - A minor problem or an opportunity to improve the code.</li> </ul> <p>In a continuous integration (CI) pipeline, severity level is particularly important. If any rule fails with a severity level of <code>Error</code> the pipeline will fail. This helps prevent serious problems from being introduced into the code base or deployed.</p> <p>The following example shows how to set the severity level to <code>Warning</code>.</p> YAMLJSONPowerShell <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  level: Warning\n  condition:\n    allOf:\n    - field: 'configure.supportsHttpsTrafficOnly'\n      equals: true\n    - field: 'configure.minTLSVersion'\n      equals: '1.2'\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"level\": \"Warning\",\n            \"condition\": {\n                \"allOf\": [\n                    {\n                        \"field\": \"configure.supportsHttpsTrafficOnly\",\n                        \"equals\": true\n                    },\n                    {\n                        \"field\": \"configure.minTLSVersion\",\n                        \"equals\": \"1.2\"\n                    }\n                ]\n            }\n        }\n    }\n]\n</code></pre> <p>Update <code>.ps-rule/Local.Rule.ps1</code> in your repository with the following contents.</p> <pre><code># Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' -Level Warning {\n    $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n    $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\n</code></pre>"},{"location":"authoring/using-expressions/","title":"Using expressions","text":"<p>PSRule allows you to write rules using YAML, JSON, or PowerShell. This offers a lot of flexibility to use PSRule for a variety of use cases. Some examples of use cases for each format include:</p> <ul> <li>YAML \u2014 Start authoring quickly with minimal knowledge of PowerShell.</li> <li>JSON \u2014 Generate rules automatically using automation tools.</li> <li>PowerShell \u2014 Integrate with other tools using PowerShell cmdlets.</li> </ul> <p>Abstract</p> <p>This topic covers the differences and limitations between authoring rules using YAML, JSON, and PowerShell. For an example of authoring rules see Writing rules or Testing infrastructure topics.</p>"},{"location":"authoring/using-expressions/#language-comparison","title":"Language comparison","text":"<p>Expressions and assertion methods can be used to build similar conditions.</p> <ul> <li>Expressions \u2014 Schema-based conditions written in YAML or JSON.   Expressions can be used in rules and selectors.</li> <li>Assertion methods \u2014 PowerShell-based condition helpers that make rules faster to author.   Assertion methods can be used in combination with standard PowerShell code to build rules or conventions.</li> </ul>"},{"location":"authoring/using-expressions/#quick-reference","title":"Quick reference","text":"<p>In most cases expressions and assertion method names match. There are some cases where these names do not directly align. This lookup table provides a quick reference for expressions and their assertion method counterpart.</p> Expression Assertion method Contains Contains Count Count Equals <sup>1</sup> n/a EndsWith EndsWith Exists HasField Greater Greater GreaterOrEquals GreaterOrEqual HasDefault HasDefaultValue HasSchema HasJsonSchema HasValue <sup>1</sup> n/a In In IsLower IsLower IsString IsString IsUpper IsUpper Less Less LessOrEquals LessOrEqual Match Match NotEquals n/a NotIn NotIn NotMatch NotMatch SetOf SetOf StartsWith StartsWith Subset Subset Version Version n/a FileHeader n/a FilePath n/a HasFields n/a HasFieldValue <sup>1</sup> IsArray IsArray IsBoolean IsBoolean IsDateTime IsDateTime IsInteger IsInteger IsNumeric IsNumeric n/a JsonSchema Exists NotHasField n/a NotNull NotWithinPath NotWithinPath n/a Null n/a NullOrEmpty n/a TypeOf WithinPath WithinPath <ol> <li> <p>The <code>Equals</code>, <code>HasValue</code> expressions and <code>HasFieldValue</code> are similar.\u00a0\u21a9\u21a9\u21a9</p> </li> </ol>"},{"location":"authoring/writing-rule-help/","title":"Writing rule help","text":"<p>PSRule has built-in support for help. Documentation can optionally be added for each rule to provide detailed information or remediation steps.</p> <p>This scenario covers the following:</p> <ul> <li>Using inline help</li> <li>Writing markdown documentation</li> <li>Localizing documentation files</li> </ul>"},{"location":"authoring/writing-rule-help/#inline-help-with-yaml-and-json","title":"Inline help with YAML and JSON","text":"<p>With authoring rules in YAML and JSON, PSRule provides the following syntax features:</p> <ul> <li>Synopsis resource comment.</li> <li><code>metadata.displayName</code> property.</li> <li><code>metadata.description</code> property.</li> <li><code>metadata.link</code> property.</li> <li><code>spec.recommend</code> property.</li> </ul>"},{"location":"authoring/writing-rule-help/#synopsis-resource-comment","title":"Synopsis resource comment","text":"<p>Specify the synopsis of the rule with the <code>Synopsis</code> comment above the rule properties.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>The resource comment is not localized. Use markdown documentation for a localized synopsis.</p>"},{"location":"authoring/writing-rule-help/#display-name-property","title":"Display name property","text":"<p>Specify the display name of the rule with the <code>metadata.displayName</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\n  displayName: Require TLS\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\",\n            \"displayName\": \"Require TLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized display name.</p>"},{"location":"authoring/writing-rule-help/#description-property","title":"Description property","text":"<p>Specify the description of the rule with the <code>metadata.description</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\n  description: The resource should only use TLS.\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\",\n            \"description\": \"The resource should only use TLS.\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized description.</p>"},{"location":"authoring/writing-rule-help/#link-property","title":"Link property","text":"<p>Specify the online help URL of the rule with the <code>metadata.link</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\n  link: https://aka.ms/ps-rule\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\",\n            \"link\": \"https://aka.ms/ps-rule\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized online help URL.</p>"},{"location":"authoring/writing-rule-help/#recommend-property","title":"Recommend property","text":"<p>Specify the rule recommendation with the <code>spec.recommend</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  recommend: The resource should only use TLS.\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"recommend\": \"\",\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized recommendation.</p>"},{"location":"authoring/writing-rule-help/#inline-help-with-powershell","title":"Inline help with PowerShell","text":"<p>When authoring rules in PowerShell, PSRule provides the following syntax features:</p> <ul> <li>Synopsis script comment.</li> <li><code>Recommend</code> keyword.</li> <li><code>Reason</code> keyword.</li> </ul> <p>These features are each describe in detail in the following sections.</p>"},{"location":"authoring/writing-rule-help/#synopsis-script-comment","title":"Synopsis script comment","text":"<p>Comment metadata can be included directly above a rule block by using the syntax <code># Synopsis: &lt;text&gt;</code>. This is only supported for populating a rule synopsis.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>This example above would set the synopsis to <code>Must have the app.kubernetes.io/name label</code>.</p> <p>Including comment metadata improves authoring by indicating the rules purpose. Only a single line is supported. A rule synopsis is displayed when using <code>Get-PSRule</code> and <code>Get-PSRuleHelp</code>. The synopsis can not break over multiple lines.</p> <p>The key limitation of only using comment metadata is that it can not be localized for multiple languages. Consider using comment metadata and also using markdown documentation for a multi-language experience.</p> <p>Note</p> <p>The script comment is not localized. Use markdown documentation for a localized synopsis.</p>"},{"location":"authoring/writing-rule-help/#recommend-keyword","title":"Recommend keyword","text":"<p>The <code>Recommend</code> keyword sets the recommendation for a rule. Use the keyword with a text recommendation at the top of your rule body.</p> <p>Using the <code>Recommend</code> keyword is recommended for rules that are not packaged in a module. When packaging rules in a module consider using markdown help instead.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend 'Consider setting the recommended label ''app.kubernetes.io/name'' on deployment and service resources.'\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>A rule recommendation is displayed when using <code>Invoke-PSRule</code> or <code>Get-PSRuleHelp</code>.</p> <p>Only use the <code>Recommend</code> keyword once to set the recommendation text and avoid formatting with variables. Recommendations are cached the first time they are used. Supplying a unique recommendation within a rule based on conditions/ logic is not supported. To return a custom unique reason for why the rule failed, use the <code>Reason</code> keyword.</p> <p>Localized recommendations can set by using the <code>$LocalizedData</code>.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend $LocalizedData.RecommendNameLabel\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre>"},{"location":"authoring/writing-rule-help/#reason-keyword","title":"Reason keyword","text":"<p>The <code>Reason</code> keyword sets the reason the rule failed when using <code>Invoke-PSRule</code> and <code>Assert-PSRule</code>. The reason is only included in detailed output if the rule did not pass. If the rule passed, then reason is empty it returned output.</p> <p>Reasons are not included in the default view when using <code>Invoke-PSRule</code>. Use <code>-OutputFormat Wide</code> to display reason messages.</p> <p>To set a reason use the <code>Reason</code> keyword followed by the reason. For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend $LocalizedData.RecommendNameLabel\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n    Reason 'The standard name label is not set.'\n}\n</code></pre> <p>The <code>Reason</code> keyword can be used multiple times within conditional logic to return a list of reasons the rule failed. Additionally the reason messages can be localized by using the <code>$LocalizedData</code> variable.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend $LocalizedData.RecommendNameLabel\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n    # $LocalizedData.ReasonLabelMissing is set to 'The standard {0} label is not set.'.\n    Reason ($LocalizedData.ReasonLabelMissing -f 'name')\n}\n</code></pre>"},{"location":"authoring/writing-rule-help/#writing-markdown-documentation","title":"Writing markdown documentation","text":"<p>In addition to inline help, documentation can be written in markdown to provide online and offline help. Extended documentation is generally easier to author using markdown. Additionally markdown documentation is easily localized.</p> <p>Markdown documentation is authored by creating one or more <code>.md</code> files, one for each rule. PSRule uses a naming convention with a file name the same as the rule to match rule to markdown.</p> <p>For example, <code>metadata.Name.md</code> would be used for a rule named <code>metadata.Name</code>.</p> <p>We recommend matching the rule name case exactly when naming markdown files. This is because some file systems are case-sensitive. For example on Linux <code>Metadata.Name.md</code> would not match.</p> <p>Within each markdown file a number of predefined sections are automatically interpreted by PSRule. While it is possible to have additional sections, they will be ignored by the help system.</p> <p>The basic structure of markdown help is as follows:</p> <pre><code>---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n## SYNOPSIS\n\n{{ A brief summary of the rule }}\n\n## DESCRIPTION\n\n{{ A detailed description of the rule }}\n\n## RECOMMENDATION\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## NOTES\n\n{{ Additional information or configuration options }}\n\n## LINKS\n\n{{ Links to external references }}\n</code></pre> <p>The PSRule Visual Studio Code extension includes snippets for writing markdown documentation.</p>"},{"location":"authoring/writing-rule-help/#annotations","title":"Annotations","text":"<p>The annotation front matter at the top of the markdown document, is a set of key value pairs. Front matter follows YAML conventions and must start on the first line of the markdown document.</p> <p>A <code>---</code> on a separate line indicates the start and end of the front matter block. Within the front matter block, all key value pairs are treated as annotations by PSRule.</p> <p>Annotations are optional metadata that are associated with the rule. Any annotations associated with a rule are included in output. Some examples of annotations include; <code>severity</code>, <code>category</code>, <code>author</code>.</p> <p>Annotations differ from tags in two key ways:</p> <ul> <li>Annotations are localized, and can have a different value for different languages; tags are not.</li> <li>Tags are indexed and can be used to filter rules; annotations have no affect on rule filtering.</li> </ul> <p>The following reserved annotation exists:</p> <ul> <li><code>online version</code> - A URL to the online version of the document, used by <code>Get-PSRuleHelp -Online</code>.</li> </ul> <pre><code>---\nonline version: https://github.com/microsoft/PSRule/blob/main/docs/scenarios/rule-docs/rule-docs.md\n---\n</code></pre> <p>The front matter start and end <code>---</code> are not required and can be removed if no annotations are defined.</p>"},{"location":"authoring/writing-rule-help/#display-name","title":"Display name","text":"<p>The document title, indicated by a level one heading <code>#</code> is the display name of the rule. The rule display name is shown when using <code>Get-PSRuleHelp</code> and is included in output.</p> <p>Specify the display name on a single line. Wrapping the display name across multiple lines is not supported.</p> <p>For example:</p> <pre><code># Use recommended name label\n</code></pre>"},{"location":"authoring/writing-rule-help/#synopsis-section","title":"Synopsis section","text":"<p>The synopsis section is indicated by the heading <code>## SYNOPSIS</code>. Any text following the heading is interpreted by PSRule and included in output. The synopsis is displayed when using <code>Get-PSRule</code> and <code>Get-PSRuleHelp</code> cmdlets.</p> <p>The synopsis is intended to be a brief description of the rule, over a single line. A good synopsis should convey the purpose of the rule. A more verbose description can be included in the description section.</p> <p>For example:</p> <pre><code>## SYNOPSIS\n\nDeployments and services must use the app.kubernetes.io/name label.\n</code></pre>"},{"location":"authoring/writing-rule-help/#description-section","title":"Description section","text":"<p>The description section is indicated by the heading <code>## DESCRIPTION</code>. Any text following the heading is interpreted by PSRule and included in output. The description is displayed when using the <code>Get-PSRuleHelp</code> cmdlet.</p> <p>The description is intended to be a verbose description of the rule. If your rule documentation needs to include background information include it here.</p> <p>PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.</p> <p>For example:</p> <pre><code>## DESCRIPTION\n\nKubernetes defines a common set of labels that are recommended for tool interoperability.\nThese labels should be used to consistently apply standard metadata.\n\nThe `app.kubernetes.io/name` label should be used to specify the name of the application.\n</code></pre>"},{"location":"authoring/writing-rule-help/#recommendation-section","title":"Recommendation section","text":"<p>The recommendation section is indicated by the heading <code>## RECOMMENDATION</code>. Any text following the heading is interpreted by PSRule and included in output. The recommendation is displayed when using the <code>Invoke-PSRule</code> and <code>Get-PSRuleHelp</code> cmdlets.</p> <p>The recommendation is intended to identify corrective actions that can be taken to address any failures. Avoid using URLs within the recommendation. Use the links section to include references to external sources.</p> <p>PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.</p> <p>For example:</p> <pre><code>## RECOMMENDATION\n\nConsider setting the recommended label `app.kubernetes.io/name` on deployment and service resources.\n</code></pre>"},{"location":"authoring/writing-rule-help/#notes-section","title":"Notes section","text":"<p>The notes section is indicated by the heading <code>## NOTES</code>. Any text following the heading is interpreted by PSRule and included in pipeline output. Notes are excluded when formatting output as YAML and JSON.</p> <p>To view any included notes use the <code>Get-PSRuleHelp</code> cmdlet with the <code>-Full</code> switch.</p> <p>Use notes to include additional information such configuration options.</p> <p>PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.</p> <p>For example:</p> <pre><code>## NOTES\n\nThe Kubernetes recommended labels include:\n\n- `app.kubernetes.io/name`\n- `app.kubernetes.io/instance`\n- `app.kubernetes.io/version`\n- `app.kubernetes.io/component`\n- `app.kubernetes.io/part-of`\n- `app.kubernetes.io/managed-by`\n</code></pre>"},{"location":"authoring/writing-rule-help/#links-section","title":"Links section","text":"<p>The links section is indicated by the heading <code>## LINKS</code>. Any markdown links following the heading are interpreted by PSRule and included in pipeline output. Links are excluded when formatting output as YAML and JSON.</p> <p>To view any included links use the <code>Get-PSRuleHelp</code> cmdlet with the <code>-Full</code> switch.</p> <p>Use links to reference external sources with a URL.</p> <p>To specify links, use the markdown syntax <code>[display name](url)</code>. Include each link on a separate line. To improve display in web rendered markdown, use a list of links by prefixing the line with <code>-</code>.</p> <p>Additional text such as <code>See additional information:</code> is useful for web rendered views, but ignored by PSRule.</p> <p>For example:</p> <pre><code>## LINKS\n\n- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)\n</code></pre>"},{"location":"authoring/writing-rule-help/#localizing-documentation-files","title":"Localizing documentation files","text":"<p>When distributing rules, you may need to provide rule help in different languages. PSRule builds on the culture system in PowerShell.</p>"},{"location":"authoring/writing-rule-help/#using-cultures","title":"Using cultures","text":"<p>A directory structure is used to identify the markdown documentation that should be used for each culture.</p> <p>To get a list of cultures in PowerShell the use cmdlet <code>Get-Culture -ListAvailable</code>.</p> <p>For example, store documentation targeted to the culture <code>en-US</code> in a directory named <code>en-US</code>. Similarly, documentation for cultures such as <code>en-AU</code>, <code>en-GB</code> and <code>fr-FR</code> would be in separate directories.</p> <p>If a directory for the exact culture <code>en-US</code> doesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory named <code>en</code>.</p> <p>When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux <code>en-us</code> would not match.</p>"},{"location":"authoring/writing-rule-help/#culture-directory-search-path","title":"Culture directory search path","text":"<p>The path that PSRule looks for a culture directory in varies depending on how the rule is redistributed. Rules can be redistributed individually (loose) or included in a module.</p> <p>The following logic is used to locate the culture directory.</p> <ul> <li>If the rules are loose, PSRule will search for the culture directory in the same subdirectory as the <code>.Rule.ps1</code> file.</li> <li>When rules are included in a module, PSRule will search for the culture directory in the same subdirectory as the module manifest .psd1 file.</li> </ul> <p>For example, loose file structure:</p> <ul> <li>.ps-rule/<ul> <li>en/<ul> <li>metadata.Name.md</li> </ul> </li> <li>en-US/<ul> <li>metadata.Name.md</li> </ul> </li> <li>fr-FR/<ul> <li>metadata.Name.md</li> </ul> </li> <li>kubernetes.Rule.ps1</li> </ul> </li> </ul> <p>Module file structure:</p> <ul> <li>Kubernetes.Rules/<ul> <li>en/<ul> <li>metadata.Name.md</li> </ul> </li> <li>en-US/<ul> <li>metadata.Name.md</li> </ul> </li> <li>fr-FR/<ul> <li>metadata.Name.md</li> </ul> </li> <li>rules/<ul> <li>kubernetes.Rule.ps1</li> </ul> </li> <li>Kubernetes.Rules.psd1</li> </ul> </li> </ul>"},{"location":"authoring/writing-rule-help/#more-information","title":"More information","text":"<ul> <li>kubernetes.Rule.ps1 - An example rule for validating name label.</li> <li>metadata.Name - An example markdown documentation file.</li> </ul>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/","title":"Use mandatory tags","text":""},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#synopsis","title":"SYNOPSIS","text":"<p>Each resource must be tagged with mandatory tags.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#description","title":"DESCRIPTION","text":"<p>Azure resources can be tagged with additional metadata. Our enterprise standard requires that the following tags are used:</p> <ul> <li>Environment</li> <li>BusinessUnit</li> <li>Department</li> <li>CostCode</li> </ul>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#recommendation","title":"RECOMMENDATION","text":"<p>Consider tagging Azure resource with mandatory tags.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#links","title":"LINKS","text":"<ul> <li>Use tags to organize your Azure resources and management hierarchy</li> </ul>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/","title":"Enforce encrypted Storage connections","text":""},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#synopsis","title":"SYNOPSIS","text":"<p>Storage accounts should only accept encrypted connections.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#description","title":"DESCRIPTION","text":"<p>An Azure Storage Account is configured to allow unencrypted connections. This does not indicate that unencrypted connections are being used.</p> <p>Unencrypted communication to storage accounts could allow disclosure of information to an untrusted party.</p> <p>Storage Accounts can be configured to require encrypted connections, by setting the Secure transfer required option. If secure transfer required is not enabled (the default), unencrypted and encrypted connections are permitted.</p> <p>When secure transfer required is enabled, attempts to connect to storage using HTTP or unencrypted SMB connections are rejected.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#recommendation","title":"RECOMMENDATION","text":"<p>Storage accounts should only accept secure traffic. Consider setting secure transfer required if there is no requirement to access storage over unencrypted connections. Also consider using Azure Policy to audit or enforce this configuration.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#links","title":"LINKS","text":"<ul> <li>Require secure transfer in Azure Storage</li> <li>Sample policy for ensuring https traffic</li> </ul>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/","title":"Use recommended name label","text":""},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#synopsis","title":"SYNOPSIS","text":"<p>Deployments and services must use the app.kubernetes.io/name label.</p>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#description","title":"DESCRIPTION","text":"<p>Kubernetes defines a common set of labels that are recommended for tool interoperability. These labels should be used to consistently apply standard metadata.</p> <p>The <code>app.kubernetes.io/name</code> label should be used to specify the name of the application.</p>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#recommendation","title":"RECOMMENDATION","text":"<p>Consider setting the recommended label <code>app.kubernetes.io/name</code> on deployment and service resources.</p>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#notes","title":"NOTES","text":"<p>The Kubernetes recommended labels include:</p> <ul> <li><code>app.kubernetes.io/name</code></li> <li><code>app.kubernetes.io/instance</code></li> <li><code>app.kubernetes.io/version</code></li> <li><code>app.kubernetes.io/component</code></li> <li><code>app.kubernetes.io/part-of</code></li> <li><code>app.kubernetes.io/managed-by</code></li> </ul>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#links","title":"LINKS","text":"<ul> <li>Recommended Labels</li> </ul>"},{"location":"commands/PSRule/en-US/Assert-PSRule/","title":"Assert-PSRule","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#synopsis","title":"SYNOPSIS","text":"<p>Evaluate objects against matching rules and assert any failures.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#input-default","title":"Input (Default)","text":"<pre><code>Assert-PSRule [-Module &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [-Convention &lt;String[]&gt;] [-Style &lt;OutputStyle&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-OutputPath &lt;String&gt;]\n [-OutputFormat &lt;OutputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;]\n [-Culture &lt;String[]&gt;] -InputObject &lt;PSObject&gt; [-ResultVariable &lt;String&gt;] [-WhatIf] [-Confirm]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputpath","title":"InputPath","text":"<pre><code>Assert-PSRule -InputPath &lt;String[]&gt; [-Module &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [-Convention &lt;String[]&gt;] [-Style &lt;OutputStyle&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-OutputPath &lt;String&gt;]\n [-OutputFormat &lt;OutputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;]\n [-Culture &lt;String[]&gt;] [-ResultVariable &lt;String&gt;] [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#description","title":"DESCRIPTION","text":"<p>Evaluate objects against matching rules and assert any failures. Objects can be specified directly from the pipeline or provided from file.</p> <p>The commands <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> provide similar functionality, as differ as follows:</p> <ul> <li><code>Invoke-PSRule</code> writes results as structured objects</li> <li><code>Assert-PSRule</code> writes results as a formatted string.</li> </ul>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-1","title":"Example 1","text":"<pre><code>@{ Name = 'Item 1' } | Assert-PSRule;\n</code></pre> <p>Evaluate a simple hashtable on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-2","title":"Example 2","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n</code></pre> <pre><code>-&gt; Fridge : System.Management.Automation.PSCustomObject\n\n   [FAIL] isFruit\n\n-&gt; Apple : System.Management.Automation.PSCustomObject\n\n   [PASS] isFruit\n\nAssert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n+          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo          : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\n</code></pre> <p>Evaluate an array of objects on the pipeline against rules loaded a specified relative path.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-3","title":"Example 3","text":"<pre><code>$items | Assert-PSRule -Module PSRule.Rules.Azure -o NUnit3 -OutputPath .\\reports\\results.xml\n</code></pre> <p>Evaluate items from a pre-installed rules module PSRule.Rules.Azure. Additionally save the results as a NUnit report.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-4","title":"Example 4","text":"<pre><code>$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\ -ResultVariable resultRecords;\n</code></pre> <p>Evaluate items and additionally save the results into a variable <code>resultRecords</code>.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>When this option is set to <code>File</code> PSRule scans the path and subdirectories specified by <code>-InputPath</code>. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-baseline","title":"-Baseline","text":"<p>Specifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.</p> <pre><code>Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-convention","title":"-Convention","text":"<p>Specifies conventions by name to execute in the pipeline when processing objects.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-name","title":"-Name","text":"<p>The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-targettype","title":"-TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>This parameter if set, overrides the <code>Input.TargetType</code> option.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option. For details see the about_PSRule_Options help topic.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputpath","title":"-OutputPath","text":"<p>Specifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is written. This parameter has no affect when <code>-OutputPath</code> is not specified.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> <li>Markdown - Output is serialized as Markdown.</li> <li>NUnit3 - Output is serialized as NUnit3 (XML).</li> <li>Csv - Output is serialized as a comma separated values (CSV).</li> <li>Sarif - Output is serialized as SARIF.</li> </ul> <p>The <code>Wide</code> format is not applicable to <code>Assert-PSRule</code>.</p> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-style","title":"-Style","text":"<p>Configures the style that results will be presented in.</p> <p>The following styles are available:</p> <ul> <li>Client - Output is written to the host directly in green/ red to indicate outcome.</li> <li>Plain - Output is written as an unformatted string. This option can be redirected to a file.</li> <li>AzurePipelines - Output is written for integration Azure Pipelines.</li> <li>GitHubActions - Output is written for integration GitHub Actions.</li> <li>VisualStudioCode - Output is written for integration with Visual Studio Code.</li> <li>Detect - Output style will be detected by checking the environment variables. This is the default.</li> </ul> <p>Detect uses the following logic:</p> <ol> <li>If the <code>TF_BUILD</code> environment variable is set to <code>true</code>, <code>AzurePipelines</code> will be used.</li> <li>If the <code>GITHUB_ACTIONS</code> environment variable is set to <code>true</code>, <code>GitHubActions</code> will be used.</li> <li>If the <code>TERM_PROGRAM</code> environment variable is set to <code>vscode</code>, <code>VisualStudioCode</code> will be used.</li> <li>Use <code>Client</code>.</li> </ol> <p>Each of these styles outputs to the host. To capture output as a string redirect the information stream. For example: <code>6&gt;&amp;1</code></p> <pre><code>Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions, VisualStudioCode, Detect\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-as","title":"-As","text":"<p>The type of results to produce. Detailed results are generated by default.</p> <p>The following result formats are available:</p> <ul> <li><code>Detail</code> - Returns pass/ fail results for each rule per object.</li> <li><code>Summary</code> - Failure or errors are shown but passing results are summarized.</li> </ul> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outcome","title":"-Outcome","text":"<p>Filter output to only show rule results with a specific outcome.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-resultvariable","title":"-ResultVariable","text":"<p>Stores output result objects in the specified variable.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"<p>You can pipe any object to Assert-PSRule.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemstring","title":"System.String","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRule</p> <p>Invoke-PSRule</p> <p>Test-PSRuleTarget</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/","title":"Export-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"<p>Exports a list of baselines.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#syntax","title":"SYNTAX","text":"<pre><code>Export-PSRuleBaseline [-Module &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Option &lt;PSRuleOption&gt;]\n [-Culture &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] -OutputPath &lt;String&gt; [-OutputEncoding &lt;OutputEncoding&gt;]\n [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#description","title":"DESCRIPTION","text":"<p>Exports a list of baselines to a file.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#example-1","title":"Example 1","text":"<pre><code>Export-PSRuleBaseline -Module PSRule.Rules.Azure -OutputFormat Yaml -OutputPath Baseline.Rule.yml\n</code></pre> <p>Exports list of baselines from <code>PSRule.Rules.Azure</code> module to file <code>Baseline.Rule.yml</code> in YAML output format.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-module","title":"-Module","text":"<p>Search for baselines definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-path","title":"-Path","text":"<p>One or more paths to search for baselines within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-name","title":"-Name","text":"<p>The name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>Yaml - Output is serialized as YAML. This is the default.</li> <li>Json - Output is serialized as JSON.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: Yaml\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputencoding","title":"-OutputEncoding","text":"<p>Sets the option <code>Output.Encoding</code>. The <code>Output.Encoding</code> option configured the encoding used to write results to file.</p> <pre><code>Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputpath","title":"-OutputPath","text":"<p>Sets the option <code>Output.Path</code>. The <code>Output.Path</code> option configures the output path the results are written to.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRuleBaseline</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/","title":"Get-PSRule","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#synopsis","title":"SYNOPSIS","text":"<p>Get a list of rule definitions.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#syntax","title":"SYNTAX","text":"<pre><code>Get-PSRule [-Module &lt;String[]&gt;] [-ListAvailable] [-OutputFormat &lt;OutputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;] [-Culture &lt;String&gt;]\n [-IncludeDependencies] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#description","title":"DESCRIPTION","text":"<p>Get a list of matching rule definitions within the search path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#example-1","title":"Example 1","text":"<pre><code>Get-PSRule;\n</code></pre> <pre><code>RuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nisFruit                                                        An example rule\n</code></pre> <p>Get a list of rule definitions from the current working path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-2","title":"Example 2","text":"<pre><code>Get-PSRule -Module PSRule.Rules.Azure;\n</code></pre> <pre><code>RuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nAzure.ACR.AdminUser                 PSRule.Rules.Azure         Use Azure AD accounts instead of using the registry adm\u2026\nAzure.ACR.MinSku                    PSRule.Rules.Azure         ACR should use the Premium or Standard SKU for producti\u2026\nAzure.AKS.MinNodeCount              PSRule.Rules.Azure         AKS clusters should have minimum number of nodes for fa\u2026\nAzure.AKS.Version                   PSRule.Rules.Azure         AKS clusters should meet the minimum version.\nAzure.AKS.UseRBAC                   PSRule.Rules.Azure         AKS cluster should use role-based access control (RBAC).\n</code></pre> <p>Get a list of rule definitions included in the module <code>PSRule.Rules.Azure</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-3","title":"Example 3","text":"<pre><code>Get-PSRule -Module PSRule.Rules.Azure -OutputFormat Wide;\n</code></pre> <pre><code>RuleName                            ModuleName                 Synopsis                     Tag\n--------                            ----------                 --------                     ---\nAzure.ACR.AdminUser                 PSRule.Rules.Azure         Use Azure AD accounts        severity='Critical'\n                                                               instead of using the         category='Security\n                                                               registry admin user.         configuration'\nAzure.ACR.MinSku                    PSRule.Rules.Azure         ACR should use the Premium   severity='Important'\n                                                               or Standard SKU for          category='Performance'\n                                                               production deployments.\nAzure.AKS.MinNodeCount              PSRule.Rules.Azure         AKS clusters should have     severity='Important'\n                                                               minimum number of nodes for  category='Reliability'\n                                                               failover and updates.\nAzure.AKS.Version                   PSRule.Rules.Azure         AKS clusters should meet     severity='Important'\n                                                               the minimum version.         category='Operations\n                                                                                            management'\nAzure.AKS.UseRBAC                   PSRule.Rules.Azure         AKS cluster should use       severity='Important'\n                                                               role-based access control    category='Security\n                                                               (RBAC).                      configuration'\n</code></pre> <p>Get a list of rule definitions included in the module <code>PSRule.Rules.Azure</code> including tags with line wrapping.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#-name","title":"-Name","text":"<p>The name of a specific rule to list. If this parameter is not specified all rules in search paths will be listed.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-listavailable","title":"-ListAvailable","text":"<p>Look for modules containing rule definitions including modules that are currently not imported.</p> <p>This switch is used with the <code>-Module</code> parameter.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Wide - Output is presented using the wide table format, which includes tags and wraps columns.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Wide, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-includedependencies","title":"-IncludeDependencies","text":"<p>When this switch is specified, dependencies of the rules that meet the <code>-Name</code> and <code>-Tag</code> filters are included even if they would normally be excluded.</p> <p>This switch has no affect when getting an unfiltered list of rules.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-baseline","title":"-Baseline","text":"<p>When specified, rules are filtered so that only rules that are included in the baselines are returned.</p> <pre><code>Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#psruledefinitionsrulesirulev1","title":"PSRule.Definitions.Rules.IRuleV1","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#related-links","title":"RELATED LINKS","text":"<p>Invoke-PSRule</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/","title":"Get-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"<p>Get a list of baselines.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#syntax","title":"SYNTAX","text":"<pre><code>Get-PSRuleBaseline [-Module &lt;String[]&gt;] [-ListAvailable] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;]\n [-Option &lt;PSRuleOption&gt;] [-Culture &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#description","title":"DESCRIPTION","text":"<p>Get a list of matching baselines within the search path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#example-1","title":"Example 1","text":"<pre><code>Get-PSRuleBaseline;\n</code></pre> <p>Get a list of baselines from the current working path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-module","title":"-Module","text":"<p>Search for baselines definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-listavailable","title":"-ListAvailable","text":"<p>Look for modules containing baselines including modules that are currently not imported.</p> <p>This switch is used with the <code>-Module</code> parameter.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-path","title":"-Path","text":"<p>One or more paths to search for baselines within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-name","title":"-Name","text":"<p>The name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#psruledefinitionsbaseline","title":"PSRule.Definitions.Baseline","text":"<p>This is the default.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#systemstring","title":"System.String","text":"<p>When you use <code>-OutputFormat Yaml</code> or <code>-OutputFormat Json</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRule</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/","title":"Get-PSRuleHelp","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#synopsis","title":"SYNOPSIS","text":"<p>Displays information about a rule.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#syntax","title":"SYNTAX","text":"<pre><code>Get-PSRuleHelp [-Module &lt;String&gt;] [-Online] [-Full] [[-Name] &lt;String[]&gt;] [-Path &lt;String&gt;]\n [-Option &lt;PSRuleOption&gt;] [-Culture &lt;String&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#description","title":"DESCRIPTION","text":"<p>The <code>Get-PSRuleHelp</code> cmdlet display information about a rule.</p> <p>By default, this cmdlet will look for rules in the current path and loaded modules. To get help for a specific rule or module use the <code>-Name</code> or <code>-Module</code> parameters.</p> <p>If the rule has an online version of the documentation, use the <code>-Online</code> parameter to view it in your default web browser.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-1","title":"Example 1","text":"<pre><code>Get-PSRuleHelp;\n</code></pre> <p>Get a list of rule help within the current path or loaded modules.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-2","title":"Example 2","text":"<pre><code>Get-PSRuleHelp Azure.ACR.AdminUser;\n</code></pre> <p>Get rule documentation for the rule <code>Azure.ACR.AdminUser</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-3","title":"Example 3","text":"<pre><code>Get-PSRuleHelp Azure.ACR.AdminUser -Online;\n</code></pre> <p>Browse to the online version of documentation for <code>Azure.ACR.AdminUser</code> using the default web browser.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-name","title":"-Name","text":"<p>The name of the rule to get documentation for.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-path","title":"-Path","text":"<p>A path to check documentation for. By default, help from the current working path and loaded modules is listed. Results can be filtered by using <code>-Name</code>, <code>-Path</code> or <code>-Module</code>.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-module","title":"-Module","text":"<p>Limit returned information to rules in the specified module. By default, help from the current working path and loaded modules is listed. Results can be filtered by using <code>-Name</code>, <code>-Path</code> or <code>-Module</code>.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-online","title":"-Online","text":"<p>Instead of displaying documentation within PowerShell, browse to the online version using the default web browser.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-full","title":"-Full","text":"<p>Display additional information such as notes and links.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#psrulerulesrulehelpinfo","title":"PSRule.Rules.RuleHelpInfo","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/","title":"Get-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"<p>Get a list of target objects.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#input-default","title":"Input (Default)","text":"<pre><code>Get-PSRuleTarget [-Format &lt;InputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;]\n -InputObject &lt;PSObject&gt; [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputpath","title":"InputPath","text":"<pre><code>Get-PSRuleTarget -InputPath &lt;String[]&gt; [-Format &lt;InputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;]\n [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#description","title":"DESCRIPTION","text":"<p>Get a list of target objects from input.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#example-1","title":"Example 1","text":"<pre><code>Get-PSRuleTarget -InputPath .\\resources.json;\n</code></pre> <p>Get target objects from <code>resources.json</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/","title":"Invoke-PSRule","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#synopsis","title":"SYNOPSIS","text":"<p>Evaluate objects against matching rules and output the results.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#input-default","title":"Input (Default)","text":"<pre><code>Invoke-PSRule [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;] [-Format &lt;InputFormat&gt;]\n [-OutputPath &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-Baseline &lt;BaselineOption&gt;] [-Convention &lt;String[]&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;]\n [-TargetType &lt;String[]&gt;] [-Culture &lt;String[]&gt;] -InputObject &lt;PSObject&gt; [-WhatIf] [-Confirm]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputpath","title":"InputPath","text":"<pre><code>Invoke-PSRule -InputPath &lt;String[]&gt; [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;]\n [-Format &lt;InputFormat&gt;] [-OutputPath &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [-Convention &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;]\n [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;] [-Culture &lt;String[]&gt;] [-WhatIf] [-Confirm]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#description","title":"DESCRIPTION","text":"<p>Evaluate objects against matching rules and output the results. Objects can be specified directly from the pipeline or provided from file.</p> <p>The commands <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> provide similar functionality, as differ as follows:</p> <ul> <li><code>Invoke-PSRule</code> writes results as structured objects</li> <li><code>Assert-PSRule</code> writes results as a formatted string.</li> </ul>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-1","title":"Example 1","text":"<pre><code>@{ Name = 'Item 1' } | Invoke-PSRule;\n</code></pre> <p>Evaluate a simple hashtable on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-2","title":"Example 2","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\n</code></pre> <pre><code>TargetName: Fridge\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Fail       Fruit is only Apple, Orange and Pear\n\n\n   TargetName: Apple\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Pass       Fruit is only Apple, Orange and Pear\n</code></pre> <p>Evaluate an array of objects on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-3","title":"Example 3","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and only return failing results\n$items | Invoke-PSRule -Outcome Fail;\n</code></pre> <pre><code>TargetName: Fridge\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Fail       Fruit is only Apple, Orange and Pear\n</code></pre> <p>Evaluate an array of objects, only failing object results are returned.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-4","title":"Example 4","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and show rule summary\n$items | Invoke-PSRule -As Summary;\n</code></pre> <pre><code>RuleName                            Pass  Fail  Outcome\n--------                            ----  ----  -------\nisFruit                             1     1     Fail\n</code></pre> <p>Evaluate an array of objects. The results for each rule is returned as a summary. Outcome is represented as the worst outcome.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-name","title":"-Name","text":"<p>The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outcome","title":"-Outcome","text":"<p>Filter output to only show rule results with a specific outcome.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-as","title":"-As","text":"<p>The type of results to produce. Detailed results are generated by default.</p> <p>The following result formats are available:</p> <ul> <li><code>Detail</code> - Returns pass/ fail results for each rule per object.</li> <li><code>Summary</code> - Returns summarized results for the rule and the worst outcome.</li> </ul> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>When this option is set to <code>File</code> PSRule scans the path and subdirectories specified by <code>-InputPath</code>. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-baseline","title":"-Baseline","text":"<p>Specifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.</p> <pre><code>Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-convention","title":"-Convention","text":"<p>Specifies conventions by name to execute in the pipeline when processing objects.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-targettype","title":"-TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>This parameter if set, overrides the <code>Input.TargetType</code> option.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option. For details see the about_PSRule_Options help topic.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputpath","title":"-OutputPath","text":"<p>Specifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> <li>Markdown - Output is serialized as Markdown.</li> <li>NUnit3 - Output is serialized as NUnit3 (XML).</li> <li>Csv - Output is serialized as a comma separated values (CSV).</li> <li>Wide - Output is presented using the wide table format, which includes reason and wraps columns.</li> <li>Sarif - Output is serialized as SARIF.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"<p>You can pipe any object to Invoke-PSRule.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulerecord","title":"PSRule.Rules.RuleRecord","text":"<p>This is the default.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulesummaryrecord","title":"PSRule.Rules.RuleSummaryRecord","text":"<p>When you use the <code>-As Summary</code>. Otherwise, it returns a <code>RuleRecord</code> object.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRule</p> <p>Assert-PSRule</p> <p>Test-PSRuleTarget</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/","title":"New-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"<p>Create options to configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#frompath-default","title":"FromPath (Default)","text":"<pre><code>New-PSRuleOption [[-Path] &lt;String&gt;] [-Configuration &lt;ConfigurationOption&gt;]\n [-SuppressTargetName &lt;SuppressionOption&gt;] [-BindTargetName &lt;BindTargetName[]&gt;]\n [-BindTargetType &lt;BindTargetName[]&gt;] [-BaselineGroup &lt;Hashtable&gt;] [-BindingIgnoreCase &lt;Boolean&gt;]\n [-BindingField &lt;Hashtable&gt;] [-BindingNameSeparator &lt;String&gt;] [-BindingPreferTargetInfo &lt;Boolean&gt;]\n [-TargetName &lt;String[]&gt;] [-TargetType &lt;String[]&gt;] [-BindingUseQualifiedName &lt;Boolean&gt;]\n [-Convention &lt;String[]&gt;] [-DuplicateResourceId &lt;ExecutionActionPreference&gt;]\n [-InitialSessionState &lt;SessionState&gt;] [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;] [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;]\n [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreRepositoryCommon &lt;Boolean&gt;] [-InputIgnoreObjectSource &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputTargetType &lt;String[]&gt;]\n [-InputPathIgnore &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromoption","title":"FromOption","text":"<pre><code>New-PSRuleOption [-Option] &lt;PSRuleOption&gt; [-Configuration &lt;ConfigurationOption&gt;]\n [-SuppressTargetName &lt;SuppressionOption&gt;] [-BindTargetName &lt;BindTargetName[]&gt;]\n [-BindTargetType &lt;BindTargetName[]&gt;] [-BaselineGroup &lt;Hashtable&gt;] [-BindingIgnoreCase &lt;Boolean&gt;]\n [-BindingField &lt;Hashtable&gt;] [-BindingNameSeparator &lt;String&gt;] [-BindingPreferTargetInfo &lt;Boolean&gt;]\n [-TargetName &lt;String[]&gt;] [-TargetType &lt;String[]&gt;] [-BindingUseQualifiedName &lt;Boolean&gt;]\n [-Convention &lt;String[]&gt;] [-DuplicateResourceId &lt;ExecutionActionPreference&gt;]\n [-InitialSessionState &lt;SessionState&gt;] [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;] [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;]\n [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreRepositoryCommon &lt;Boolean&gt;] [-InputIgnoreObjectSource &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputTargetType &lt;String[]&gt;]\n [-InputPathIgnore &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromdefault","title":"FromDefault","text":"<pre><code>New-PSRuleOption [-Default] [-Configuration &lt;ConfigurationOption&gt;] [-SuppressTargetName &lt;SuppressionOption&gt;]\n [-BindTargetName &lt;BindTargetName[]&gt;] [-BindTargetType &lt;BindTargetName[]&gt;] [-BaselineGroup &lt;Hashtable&gt;]\n [-BindingIgnoreCase &lt;Boolean&gt;] [-BindingField &lt;Hashtable&gt;] [-BindingNameSeparator &lt;String&gt;]\n [-BindingPreferTargetInfo &lt;Boolean&gt;] [-TargetName &lt;String[]&gt;] [-TargetType &lt;String[]&gt;]\n [-BindingUseQualifiedName &lt;Boolean&gt;] [-Convention &lt;String[]&gt;]\n [-DuplicateResourceId &lt;ExecutionActionPreference&gt;] [-InitialSessionState &lt;SessionState&gt;]\n [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;] [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;] [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreRepositoryCommon &lt;Boolean&gt;] [-InputIgnoreObjectSource &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputTargetType &lt;String[]&gt;]\n [-InputPathIgnore &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#description","title":"DESCRIPTION","text":"<p>The New-PSRuleOption cmdlet creates an options object that can be passed to PSRule cmdlets to configure execution.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-1","title":"Example 1","text":"<pre><code>$option = New-PSRuleOption -Option @{ 'execution.mode' = 'ConstrainedLanguage' }\n@{ Name = 'Item 1' } | Invoke-PSRule -Option $option\n</code></pre> <p>Create an options object and run rules in constrained mode.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-2","title":"Example 2","text":"<pre><code>$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\n</code></pre> <p>Create an options object that suppresses <code>TestObject1</code> and <code>TestObject3</code> for a rule named <code>storageAccounts.UseHttps</code>.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-3","title":"Example 3","text":"<pre><code># Create a custom function that returns a TargetName string\n$bindFn = {\n    param ($TargetObject)\n\n    $otherName = $TargetObject.PSObject.Properties['OtherName'];\n\n    if ($otherName -eq $Null) {\n        return $Null\n    }\n\n    return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\n</code></pre> <p>Creates an options object that uses a custom function to bind the TargetName of an object.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-4","title":"Example 4","text":"<pre><code>$option = New-PSRuleOption -Configuration @{ 'appServiceMinInstanceCount' = 2 };\n</code></pre> <p>Create an options object that sets the <code>appServiceMinInstanceCount</code> baseline configuration option to <code>2</code>.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-option","title":"-Option","text":"<p>Additional options that configure execution. Option also accepts a hashtable to configure options. See about_PSRule_Options for more information.</p> <pre><code>Type: PSRuleOption\nParameter Sets: FromOption\nAliases:\n\nRequired: True\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-path","title":"-Path","text":"<p>The path to a YAML file containing options.</p> <p>Either a directory or file path can be specified. When a directory is used, <code>ps-rule.yaml</code> will be used as the file name.</p> <p>If the <code>-Path</code> parameter is specified and the file does not exist, an exception will be generated.</p> <pre><code>Type: String\nParameter Sets: FromPath\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-default","title":"-Default","text":"<p>When specified, defaults are used for any options not overridden.</p> <pre><code>Type: SwitchParameter\nParameter Sets: FromDefault\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppresstargetname","title":"-SuppressTargetName","text":"<p>Configures suppression for a list of objects by TargetName. SuppressTargetName also accepts a hashtable to configure rule suppression. See about_PSRule_Options for more information.</p> <pre><code>Type: SuppressionOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargetname","title":"-BindTargetName","text":"<p>Configures a custom function to use to bind TargetName of an object. See about_PSRule_Options for more information.</p> <pre><code>Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-configuration","title":"-Configuration","text":"<p>Configures a set of baseline configuration values that can be used in rule definitions instead of using hard coded values. Configuration also accepts a hashtable of configuration values as key/ value pairs. See about_PSRule_Options for more information.</p> <pre><code>Type: ConfigurationOption\nParameter Sets: (All)\nAliases: BaselineConfiguration\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"<p>Sets the option <code>Baseline.Group</code>. The option <code>Baseline.Group</code> allows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargettype","title":"-BindTargetType","text":"<p>Configures a custom function to use to bind TargetType of an object. See about_PSRule_Options for more information.</p> <pre><code>Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"<p>Sets the option <code>Binding.IgnoreCase</code>. The option <code>Binding.IgnoreCase</code> determines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingfield","title":"-BindingField","text":"<p>Sets the option <code>Binding.Field</code>. The option specified one or more custom field bindings. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"<p>Sets the option <code>Binding.NameSeparator</code>. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"<p>Sets the option <code>Binding.PreferTargetInfo</code>. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-convention","title":"-Convention","text":"<p>Sets the <code>Option.ConventionInclude</code> option. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targetname","title":"-TargetName","text":"<p>Sets the option <code>Binding.TargetName</code>. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targettype","title":"-TargetType","text":"<p>Sets the option <code>Binding.TargetType</code>. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"<p>Sets the option <code>Binding.UseQualifiedName</code>. This option specifies is qualified target names are used. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"<p>Sets the <code>Execution.AliasReference</code> option. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"<p>Sets the <code>Execution.InvariantCulture</code> option. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"<p>Sets the <code>Execution.RuleInconclusive</code> option. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"<p>Sets the <code>Execution.UnprocessedObject</code> option. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"<p>Sets the <code>Include.Module</code> option to include additional module sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includepath","title":"-IncludePath","text":"<p>Sets the <code>Include.Path</code> option to include additional standalone sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-format","title":"-Format","text":"<p>Sets the <code>Input.Format</code> option to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"<p>Sets the <code>Input.IgnoreGitPath</code> option to determine if files within the .git path are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"<p>Sets the <code>Input.IgnoreRepositoryCommon</code> option to determine if files common repository files are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"<p>Sets the option <code>Input.IgnoreUnchangedPath</code>. The <code>Input.IgnoreUnchangedPath</code> option determine if unchanged files are ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"<p>Sets the <code>Input.ObjectPath</code> option to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"<p>Sets the <code>Input.PathIgnore</code> option. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"<p>Sets the <code>Input.TargetType</code> option to only process objects with the specified TargetType. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"<p>Sets the option <code>Input.IgnoreObjectSource</code>. The <code>Input.IgnoreObjectSource</code> option determines if objects will be skipped if the source path has been ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"<p>Sets the <code>Logging.LimitDebug</code> option to limit debug messages to a list of named debug scopes. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"<p>Sets the <code>Logging.LimitVerbose</code> option to limit verbose messages to a list of named verbose scopes. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"<p>Sets the <code>Logging.RuleFail</code> option to generate an informational message for each rule fail. See about_PSRule_Options for more information.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"<p>Sets the <code>Logging.RulePass</code> option to generate an informational message for each rule pass. See about_PSRule_Options for more information.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputas","title":"-OutputAs","text":"<p>Sets the option <code>Output.As</code>. The <code>Output.As</code> option configures the type of results to produce, either detail or summary.</p> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"<p>Sets the option <code>Output.Banner</code>. The <code>Output.Banner</code> option configure information displayed with PSRule banner. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <pre><code>Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"<p>Sets the option <code>Output.Culture</code>. The <code>Output.Culture</code> option configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"<p>Sets the option <code>Output.Encoding</code>. The <code>Output.Encoding</code> option configured the encoding used to write results to file.</p> <pre><code>Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"<p>Sets the option <code>Output.Footer</code>. The <code>Output.Footer</code> option configures the information displayed for PSRule footer. See about_PSRule_Options for more information.</p> <pre><code>Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"<p>Sets the option <code>Output.Format</code>. The <code>Output.Format</code> option configures the format that results will be presented in. See about_PSRule_Options for more information.</p> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"<p>Set the option <code>Output.JobSummaryPath</code>. The <code>Output.JobSummaryPath</code> option configures the path to a job summary output file.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"<p>Sets the option <code>Output.JsonIndent</code>. The <code>Output.JsonIndent</code> option configures indentation for JSON output.</p> <p>This option only applies to <code>Get-PSRule</code>, <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> cmdlets.</p> <pre><code>Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"<p>Sets the <code>Output.Outcome</code> option. This option can be set to include or exclude output results. See about_PSRule_Options for more information.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputpath","title":"-OutputPath","text":"<p>Sets the option <code>Output.Path</code>. The <code>Output.Path</code> option configures an output file path to write results.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"<p>Sets the option <code>Option.SarifProblemsOnly</code>. The <code>Output.SarifProblemsOnly</code> option determines if SARIF output only includes fail and error outcomes.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"<p>Sets the option <code>Option.Style</code>. The <code>Output.Style</code> option configures the style that results will be presented in.</p> <p>This option only applies to <code>Assert-PSRule</code>.</p> <pre><code>Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"<p>Sets the option <code>Repository.BaseRef</code>. The <code>Repository.BaseRef</code> option sets the repository base ref used for comparisons of changed files.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"<p>Sets the option <code>Repository.Url</code>. The <code>Repository.Url</code> option sets the repository URL reported in output.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"<p>Sets the option <code>Rule.IncludeLocal</code>. The <code>Rule.IncludeLocal</code> option configures if local rules are automatically included. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"<p>Sets the option <code>Execution.DuplicateResourceId</code>. The <code>Execution.DuplicateResourceId</code> option determines how to handle duplicate resources identifiers during execution.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"<p>Sets the option <code>Execution.InitialSessionState</code>. The <code>Execution.InitialSessionState</code> option determines how the initial session state for executing PowerShell code is created.</p> <pre><code>Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"<p>Sets the option <code>Execution.RuleExcluded</code>. The <code>Execution.RuleExcluded</code> option determines how to handle excluded rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"<p>Sets the option <code>Execution.RuleSuppressed</code>. The <code>Execution.RuleSuppressed</code> option determines how to handle suppressed rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"<p>Sets the option <code>Execution.SuppressionGroupExpired</code>. The <code>Execution.SuppressionGroupExpired</code> option determines how to handle expired suppression groups.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#related-links","title":"RELATED LINKS","text":"<p>Invoke-PSRule</p> <p>Set-PSRuleOption</p>"},{"location":"commands/PSRule/en-US/PSRule/","title":"PSRule Module","text":""},{"location":"commands/PSRule/en-US/PSRule/#description","title":"Description","text":"<p>A PowerShell rules engine.</p>"},{"location":"commands/PSRule/en-US/PSRule/#psrule-cmdlets","title":"PSRule Cmdlets","text":""},{"location":"commands/PSRule/en-US/PSRule/#assert-psrule","title":"Assert-PSRule","text":"<p>Evaluate objects against matching rules and assert any failures.</p>"},{"location":"commands/PSRule/en-US/PSRule/#export-psrulebaseline","title":"Export-PSRuleBaseline","text":"<p>Exports a list of baselines to a file.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psrule","title":"Get-PSRule","text":"<p>Get a list of matching rule definitions within the search path.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulebaseline","title":"Get-PSRuleBaseline","text":"<p>Get a list of matching baselines within the search path.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulehelp","title":"Get-PSRuleHelp","text":"<p>Get documentation for a rule.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psruletarget","title":"Get-PSRuleTarget","text":"<p>Get a list of target object.</p>"},{"location":"commands/PSRule/en-US/PSRule/#invoke-psrule","title":"Invoke-PSRule","text":"<p>Evaluate objects against matching rules and output the results.</p>"},{"location":"commands/PSRule/en-US/PSRule/#new-psruleoption","title":"New-PSRuleOption","text":"<p>Create options to configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/PSRule/#set-psruleoption","title":"Set-PSRuleOption","text":"<p>Set options to configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/PSRule/#test-psruletarget","title":"Test-PSRuleTarget","text":"<p>Evaluate pipeline objects against matching rules.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/","title":"Set-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"<p>Sets options that configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#syntax","title":"SYNTAX","text":"<pre><code>Set-PSRuleOption [[-Path] &lt;String&gt;] [-Option &lt;PSRuleOption&gt;] [-PassThru] [-Force] [-AllowClobber]\n [-BaselineGroup &lt;Hashtable&gt;] [-BindingIgnoreCase &lt;Boolean&gt;] [-BindingField &lt;Hashtable&gt;]\n [-BindingNameSeparator &lt;String&gt;] [-BindingPreferTargetInfo &lt;Boolean&gt;] [-TargetName &lt;String[]&gt;]\n [-TargetType &lt;String[]&gt;] [-BindingUseQualifiedName &lt;Boolean&gt;] [-Convention &lt;String[]&gt;]\n [-DuplicateResourceId &lt;ExecutionActionPreference&gt;] [-InitialSessionState &lt;SessionState&gt;]\n [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;] [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;] [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreObjectSource &lt;Boolean&gt;] [-InputIgnoreRepositoryCommon &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputPathIgnore &lt;String[]&gt;]\n [-InputTargetType &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#description","title":"DESCRIPTION","text":"<p>Sets options that configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-1","title":"Example 1","text":"<pre><code>PS C:\\&gt; Set-PSRuleOption -OutputFormat Yaml;\n</code></pre> <p>Sets the <code>Output.Format</code> to <code>Yaml</code> for <code>ps-rule.yaml</code> in the current working path. If the <code>ps-rule.yaml</code> file exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-2","title":"Example 2","text":"<pre><code>PS C:\\&gt; Set-PSRuleOption -OutputFormat Yaml -Path .\\project-options.yaml;\n</code></pre> <p>Sets the <code>Output.Format</code> to <code>Yaml</code> for <code>project-options.yaml</code> in the current working path. If the <code>project-options.yaml</code> file exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-path","title":"-Path","text":"<p>The path to a YAML file where options will be set.</p> <p>Either a directory or file path can be specified. When a directory is used, <code>ps-rule.yaml</code> will be used as the file name.</p> <p>The file will be created if it does not exist. If the file already exists it will be merged with the existing options and overwritten.</p> <p>If the directory does not exist an error will be generated. To force the creation of the directory path use the <code>-Force</code> switch.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-option","title":"-Option","text":"<p>An options object to use.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-passthru","title":"-PassThru","text":"<p>Use this option to return the options object to the pipeline instead of saving to disk.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-force","title":"-Force","text":"<p>Force creation of directory path for Path parameter, when the directory does not already exist.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-allowclobber","title":"-AllowClobber","text":"<p>Overwrite YAML files that contain comments.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"<p>Sets the option <code>Baseline.Group</code>. The option <code>Baseline.Group</code> allows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"<p>Sets the option <code>Binding.IgnoreCase</code>. The option <code>Binding.IgnoreCase</code> determines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingfield","title":"-BindingField","text":"<p>Sets the option <code>Binding.Field</code>. The option specified one or more custom field bindings. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"<p>Sets the option <code>Binding.NameSeparator</code>. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"<p>Sets the option <code>Binding.PreferTargetInfo</code>. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-convention","title":"-Convention","text":"<p>Sets the <code>Option.ConventionInclude</code> option. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targetname","title":"-TargetName","text":"<p>Sets the option <code>Binding.TargetName</code>. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targettype","title":"-TargetType","text":"<p>Sets the option <code>Binding.TargetType</code>. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"<p>Sets the option <code>Binding.UseQualifiedName</code>. This option specifies is qualified target names are used. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"<p>Sets the <code>Execution.AliasReference</code> option. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"<p>Sets the <code>Execution.InvariantCulture</code> option. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"<p>Sets the <code>Execution.RuleInconclusive</code> option. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"<p>Sets the <code>Execution.UnprocessedObject</code> option. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"<p>Sets the <code>Include.Module</code> option to include additional module sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includepath","title":"-IncludePath","text":"<p>Sets the <code>Include.Path</code> option to include additional standalone sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-format","title":"-Format","text":"<p>Sets the <code>Input.Format</code> option to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"<p>Sets the <code>Input.IgnoreGitPath</code> option to determine if files within the .git path are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"<p>Sets the <code>Input.IgnoreRepositoryCommon</code> option to determine if files common repository files are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"<p>Sets the option <code>Input.IgnoreUnchangedPath</code>. The <code>Input.IgnoreUnchangedPath</code> option determine if unchanged files are ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"<p>Sets the <code>Input.ObjectPath</code> option to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"<p>Sets the <code>Input.PathIgnore</code> option. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"<p>Sets the <code>Input.TargetType</code> option to only process objects with the specified TargetType.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"<p>Sets the option <code>Input.IgnoreObjectSource</code>. The <code>Input.IgnoreObjectSource</code> option determines if objects will be skipped if the source path has been ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"<p>Sets the <code>Logging.LimitDebug</code> option to limit debug messages to a list of named debug scopes.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"<p>Sets the <code>Logging.LimitVerbose</code> option to limit verbose messages to a list of named verbose scopes.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"<p>Sets the <code>Logging.RuleFail</code> option to generate an informational message for each rule fail.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"<p>Sets the <code>Logging.RulePass</code> option to generate an informational message for each rule pass.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputas","title":"-OutputAs","text":"<p>Sets the option <code>Output.As</code>. The <code>Output.As</code> option configures the type of results to produce, either detail or summary.</p> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"<p>Sets the option <code>Output.Banner</code>. The <code>Output.Banner</code> option configure information displayed with PSRule banner. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <pre><code>Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"<p>Sets the option <code>Output.Culture</code>. The <code>Output.Culture</code> option configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"<p>Sets the option <code>Output.Encoding</code>. The <code>Output.Encoding</code> option configured the encoding used to write results to file.</p> <pre><code>Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"<p>Sets the option <code>Output.Footer</code>. The <code>Output.Footer</code> option configures the information displayed for PSRule footer. See about_PSRule_Options for more information.</p> <pre><code>Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"<p>Sets the option <code>Output.Format</code>. The <code>Output.Format</code> option configures the format that results will be presented in.</p> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"<p>Set the option <code>Output.JobSummaryPath</code>. The <code>Output.JobSummaryPath</code> option configures the path to a job summary output file.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"<p>Sets the option <code>Output.JsonIndent</code>. The <code>Output.JsonIndent</code> option configures indentation for JSON output.</p> <p>This option only applies to <code>Get-PSRule</code>, <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> cmdlets.</p> <pre><code>Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"<p>Sets the <code>Output.Outcome</code> option. This option can be set to include or exclude output results. See about_PSRule_Options for more information.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputpath","title":"-OutputPath","text":"<p>Sets the option <code>Output.Path</code>. The <code>Output.Path</code> option configures an output file path to write results.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"<p>Sets the option <code>Option.SarifProblemsOnly</code>. The <code>Output.SarifProblemsOnly</code> option determines if SARIF output only includes fail and error outcomes.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"<p>Sets the option <code>Option.Style</code>. The <code>Output.Style</code> option configures the style that results will be presented in.</p> <p>This option only applies to <code>Assert-PSRule</code>.</p> <pre><code>Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"<p>Sets the option <code>Repository.BaseRef</code>. The <code>Repository.BaseRef</code> option sets the repository base ref used for comparisons of changed files.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"<p>Sets the option <code>Repository.Url</code>. The <code>Repository.Url</code> option sets the repository URL reported in output.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"<p>Sets the option <code>Rule.IncludeLocal</code>. The <code>Rule.IncludeLocal</code> option configures if local rules are automatically included. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"<p>Sets the option <code>Execution.DuplicateResourceId</code>. The <code>Execution.DuplicateResourceId</code> option determines how to handle duplicate resources identifiers during execution.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"<p>Sets the option <code>Execution.InitialSessionState</code>. The <code>Execution.InitialSessionState</code> option determines how the initial session state for executing PowerShell code is created.</p> <pre><code>Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"<p>Sets the option <code>Execution.RuleExcluded</code>. The <code>Execution.RuleExcluded</code> option determines how to handle excluded rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"<p>Sets the option <code>Execution.RuleSuppressed</code>. The <code>Execution.RuleSuppressed</code> option determines how to handle suppressed rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"<p>Sets the option <code>Execution.SuppressionGroupExpired</code>. The <code>Execution.SuppressionGroupExpired</code> option determines how to handle expired suppression groups.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":"<p>When you use the <code>-PassThru</code> switch, an options object is returned to the pipeline.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#related-links","title":"RELATED LINKS","text":"<p>New-PSRuleOption</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/","title":"Test-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"<p>Pass or fail objects against matching rules.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#input-default","title":"Input (Default)","text":"<pre><code>Test-PSRuleTarget [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-Format &lt;InputFormat&gt;]\n [-Convention &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] -InputObject &lt;PSObject&gt;\n [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;] [-Culture &lt;String&gt;]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputpath","title":"InputPath","text":"<pre><code>Test-PSRuleTarget -InputPath &lt;String[]&gt; [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-Format &lt;InputFormat&gt;]\n [-Convention &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;]\n [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;] [-Culture &lt;String&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#description","title":"DESCRIPTION","text":"<p>Evaluate objects against matching rules and return an overall pass or fail for the object as <code>$True</code> (pass) or <code>$False</code> (fail).</p> <p>PSRule uses the following logic to determine overall pass or fail for an object:</p> <ul> <li>The object fails if:<ul> <li>Any rules fail or error.</li> <li>Any rules are inconclusive.</li> </ul> </li> <li>The object passes if:<ul> <li>No matching rules were found.</li> <li>All rules pass.</li> </ul> </li> </ul> <p>By default, objects that do match any rules are not returned in results. To return <code>$True</code> for these objects, use <code>-Outcome All</code>.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#example-1","title":"Example 1","text":"<pre><code>@{ Name = 'Item 1' } | Test-PSRuleTarget;\n</code></pre> <p>Evaluate a simple hashtable on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <p>If the <code>-Module</code> parameter is used, rule definitions from the currently working path will not be included by default.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-name","title":"-Name","text":"<p>The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-outcome","title":"-Outcome","text":"<p>Filter output to only show pipeline objects with a specific outcome.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>When this option is set to <code>File</code> PSRule scans the path and subdirectories specified by <code>-InputPath</code>. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, Repository, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-convention","title":"-Convention","text":"<p>Specifies conventions by name to execute in the pipeline when processing objects.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-targettype","title":"-TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>This parameter if set, overrides the <code>Input.TargetType</code> option.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option. For details see the about_PSRule_Options help topic.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. When specified without the <code>-Path</code> parameter, only rule definitions in the module will be discovered.</p> <p>When both <code>-Path</code> and <code>-Module</code> are specified, rule definitions from both are discovered.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"<p>You can pipe any object to Test-PSRuleTarget.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemboolean","title":"System.Boolean","text":"<p>Returns <code>$True</code> when the object passes and <code>$False</code> when the object fails.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#related-links","title":"RELATED LINKS","text":"<p>Invoke-PSRule</p> <p>Assert-PSRule</p> <p>Get-PSRule</p>"},{"location":"concepts/baselines/","title":"Baselines","text":"<p>Abstract</p> <p>A baseline is a set of rules and configuration options. You can define a named baseline to run a set of rules for a specific use case.</p> <p>Baselines cover two (2) main scenarios:</p> <ul> <li>Rules \u2014 PSRule supports running rules by name or tag.   However, when working with a large number of rules it is often easier to group and run rules based on a name.</li> <li>Configuration \u2014 A baseline allows you to run any included rules with a predefined configuration by name.</li> </ul>"},{"location":"concepts/baselines/#defining-baselines","title":"Defining baselines","text":"<p>A baseline is defined as a resource within YAML or JSON. Baselines can be defined side-by-side with rules you create or included separately as a custom baseline.</p> <p>Continue reading baseline reference.</p>"},{"location":"concepts/baselines/#baseline-groups","title":"Baseline groups","text":"<p> v2.9.0</p> <p>In addition to regular baselines, you can use a baseline group to provide a friendly name to an existing baseline. A baseline groups are set by configuring the Baseline.Group option.</p> <p>Experimental</p> <p>Baseline groups are a work in progress and subject to change. Currently, baseline groups allow only a single baseline to be referenced. Join or start a discussion to let us know how we can improve this feature going forward.</p> <p>Tip</p> <p>You can use baseline groups to reference a baseline. If a new baseline is made available in the future, update your baseline group in one place to start using the new baseline.</p> <p>In the following example, two baseline groups <code>latest</code> and <code>preview</code> are defined:</p> ps-rule.yaml<pre><code>baseline:\n  group:\n    latest: PSRule.Rules.Azure\\Azure.GA_2023_03\n    preview: PSRule.Rules.Azure\\Azure.Preview_2023_03\n</code></pre> <ul> <li>The <code>latest</code> baseline group is set to <code>Azure.GA_2023_03</code> within the <code>PSRule.Rules.Azure</code> module.</li> <li>The <code>preview</code> baseline group is set to <code>Azure.Preview_2023_03</code> within the <code>PSRule.Rules.Azure</code> module.</li> </ul> <p>To use the baseline group, prefix the group name with <code>@</code> when running PSRule. For example:</p> GitHub ActionsAzure PipelinesGeneric with PowerShell <pre><code>- name: Run PSRule\n  uses: microsoft/ps-rule@v2.9.0\n  with:\n    modules: 'PSRule.Rules.Azure'\n    baseline: '@latest'\n</code></pre> <pre><code>- task: ps-rule-assert@2\n  displayName: Run PSRule\n  inputs:\n    modules: 'PSRule.Rules.Azure'\n    baseline: '@latest'\n</code></pre> <pre><code>Assert-PSRule -InputPath '.' -Baseline '@latest' -Module PSRule.Rules.Azure -Format File;\n</code></pre>"},{"location":"concepts/grouping-rules/","title":"Grouping rules","text":"<p>Abstract</p> <p>Labels are additional metadata that can be used to classify rules. Together with tags they can be used to group or filter rules.</p>"},{"location":"concepts/grouping-rules/#using-labels","title":"Using labels","text":"<p>When defining a rule you can specify labels to classify or link rules using a framework or standard. A single rule can be can linked to multiple labels. For example:</p> <ul> <li>The Azure Well-Architected Framework (WAF) defines pillars such as Security and Reliability.</li> <li>The CIS Benchmarks define a number of control IDs such as 3.12 and 13.4.</li> </ul> YAMLJSONPowerShell <p>To specify labels in YAML, use the <code>labels</code> property:</p> <pre><code>---\n# Synopsis: A rule with labels defined.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: WithLabels\n  labels:\n    Azure.WAF/pillar: Security\n    Azure.ASB.v3/control: [ 'ID-1', 'ID-2' ]\nspec: { }\n</code></pre> <p>To specify labels in JSON, use the <code>labels</code> property:</p> <pre><code>{\n  // Synopsis: A rule with labels defined.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"WithLabels\",\n    \"labels\": {\n      \"Azure.WAF/pillar\": \"Security\",\n      \"Azure.ASB.v3/control\": [ \"ID-1\", \"ID-2\" ]\n    }\n  },\n  \"spec\": { }\n}\n</code></pre> <p>To specify labels in PowerShell, use the <code>-Labels</code> parameter:</p> <pre><code># Synopsis: A rule with labels defined.\nRule 'WithLabels' -Labels @{ 'Azure.WAF/pillar' = 'Security'; 'Azure.ASB.v3/control' = @('ID-1', 'ID-2') } {\n    # Define conditions here\n} \n</code></pre>"},{"location":"concepts/grouping-rules/#filtering-with-labels","title":"Filtering with labels","text":"<p>A reason for assigning labels to rules is to perform filtering of rules to a specific subset. This can be accomplished using baselines and the <code>spec.rule.labels</code> property. For example:</p> <pre><code>---\n# Synopsis: A baseline which returns only security rules.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline6\nspec:\n  rule:\n    labels:\n      Azure.WAF/pillar: [ 'Security' ]\n\n---\n# Synopsis: A baseline which returns any rules that are classified to Azure.WAF/pillar.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline6\nspec:\n  rule:\n    labels:\n      Azure.WAF/pillar: '*'\n</code></pre>"},{"location":"concepts/lockfile/","title":"Lock file","text":"<p>Abstract</p> <p>PSRule v3 and later uses a lock file to define the modules and versions used to run analysis. This article describes the lock file and how to manage it.</p> <p>An optional lock file can be used to define the modules and versions used to run analysis. Using the lock file ensures that the same modules and versions are used across multiple machines, improving consistency.</p> <ul> <li>Lock file is present - PSRule will use the module versions defined in the lock file.</li> <li>Lock file is not present - PSRule will use the latest version of each module installed locally.</li> </ul> Name Supports lock file PowerShell No CLI Yes, v3 and later GitHub Actions Yes, v3 and later Azure Pipelines Yes, v3 task and later Visual Studio Code Yes, v3 and later <p>Important</p> <p>The lock file only applies to PSRule outside of PowerShell. When using PSRule as a PowerShell module, the lock file is ignored.</p>"},{"location":"concepts/lockfile/#restoring-modules","title":"Restoring modules","text":"<p>When the lock file is present, PSRule will restore the modules and versions defined in the lock file.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/","title":"Assertion methods","text":"<p>Describes the assertion helper that can be used within PSRule rule definitions.</p>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#description","title":"Description","text":"<p>PSRule includes an assertion helper exposed as a built-in variable <code>$Assert</code>. The <code>$Assert</code> object provides a consistent set of methods to evaluate objects.</p> <p>Each <code>$Assert</code> method returns an <code>AssertResult</code> object that contains the result of the assertion.</p> <p>The following built-in assertion methods are provided:</p> <ul> <li>APIVersion - The field value must be a date version string.</li> <li>Contains - The field value must contain at least one of the strings.</li> <li>Count - The field value must contain the specified number of items.</li> <li>EndsWith - The field value must match at least one suffix.</li> <li>FileHeader - The file must contain a comment header.</li> <li>FilePath - The file path must exist.</li> <li>Greater - The field value must be greater.</li> <li>GreaterOrEqual - The field value must be greater or equal to.</li> <li>HasDefaultValue - The object should not have the field or the field value is set to the default value.</li> <li>HasField - The object must have any of the specified fields.</li> <li>HasFields - The object must have all of the specified fields.</li> <li>HasFieldValue - The object must have the specified field and that field is not empty.</li> <li>HasJsonSchema - The object must reference a JSON schema with the <code>$schema</code> field.</li> <li>In - The field value must be included in the set.</li> <li>IsArray - The field value must be an array.</li> <li>IsBoolean - The field value must be a boolean.</li> <li>IsDateTime - The field value must be a DateTime.</li> <li>IsInteger - The field value must be an integer.</li> <li>IsLower - The field value must include only lowercase characters.</li> <li>IsNumeric - The field value must be a numeric type.</li> <li>IsString - The field value must be a string.</li> <li>IsUpper - The field value must include only uppercase characters.</li> <li>JsonSchema - The object must validate successfully against a JSON schema.</li> <li>Less - The field value must be less.</li> <li>LessOrEqual - The field value must be less or equal to.</li> <li>Like - The value must match any of the specified wildcard values.</li> <li>Match - The field value matches a regular expression pattern.</li> <li>NotContains - The value must not contain any of the specified strings.</li> <li>NotCount - The field value must not contain the specified number of items.</li> <li>NotEndsWith - The value must not end with any of the specified strings.</li> <li>NotHasField - The object must not have any of the specified fields.</li> <li>NotIn - The field value must not be included in the set.</li> <li>NotLike - The value must not match any of the specified wildcard values.</li> <li>NotMatch - The field value does not match a regular expression pattern.</li> <li>NotNull - The field value must not be null.</li> <li>NotStartsWith - The value must not start with any of the specified strings.</li> <li>NotWithinPath - The field must not be within the specified path.</li> <li>Null - The field value must not exist or be null.</li> <li>NullOrEmpty - The object must not have the specified field or it must be empty.</li> <li>TypeOf - The field value must be of the specified type.</li> <li>SetOf - The field value must match a set of specified values.</li> <li>StartsWith - The field value must match at least one prefix.</li> <li>Subset - The field value must include a set of specified values.</li> <li>Version - The field value must be a semantic version string.</li> <li>WithinPath - The field value must be within the specified path.</li> </ul> <p>The <code>$Assert</code> variable can only be used within a rule definition block or script pre-conditions.</p>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#using-assertion-methods","title":"Using assertion methods","text":"<p>An assertion method can be used like other methods in PowerShell. i.e. <code>$Assert.methodName(parameters)</code>.</p> <p>Assertion methods use the following standard pattern:</p> <ul> <li>The first parameter is always the input object of type <code>PSObject</code>, additional parameters can be included based on the functionality required by the method.<ul> <li>In many cases the input object will be <code>$TargetObject</code>, however assertion methods must not assume that <code>$TargetObject</code> will be used.</li> <li>Assertion methods must accept a <code>$Null</code> input object.</li> </ul> </li> <li>Assertion methods return the <code>AssertResult</code> object that is interpreted by the rule pipeline.</li> </ul> <p>Some assertion methods may overlap or provide similar functionality to built-in keywords. Where you have the choice, use built-in keywords. Use assertion methods for advanced cases or increased flexibility.</p> <p>In the following example, <code>Assert.HasFieldValue</code> asserts that <code>$TargetObject</code> should have a field named <code>Type</code> with a non-empty value.</p> <pre><code>Rule 'Assert.HasTypeField' {\n    $Assert.HasFieldValue($TargetObject, 'Type')\n}\n</code></pre> <p>To find perform multiple assertions use.</p> <pre><code>Rule 'Assert.HasRequiredFields' {\n    $Assert.HasFieldValue($TargetObject, 'Name')\n    $Assert.HasFieldValue($TargetObject, 'Type')\n    $Assert.HasFieldValue($TargetObject, 'Value')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#field-names","title":"Field names","text":"<p>Many of the built-in assertion methods accept an object path or field name. An object path is an expression that traverses object properties, keys or indexes of the input object. The syntax for an object path is inspired by JSONPath which is current an IETF Internet-Draft.</p> <p>The object path expression can contain:</p> <ul> <li>Property names for PSObjects or .NET objects.</li> <li>Keys for hash table or dictionaries.</li> <li>Indexes for arrays or collections.</li> <li>Queries that filter items from array or collection properties.</li> </ul> <p>For example:</p> <ul> <li><code>.</code>, or <code>$</code> refers to input object itself.</li> <li><code>Name</code>, <code>.Name</code>, or <code>$.Name</code> refers to the name member of the input object.</li> <li><code>Properties.enabled</code> refers to the enabled member under the Properties member.   Alternatively this can also be written as <code>Properties['enabled']</code>.</li> <li><code>Tags.env</code> refers to the env member under a hash table property of the input object.</li> <li><code>Tags+env</code> refers to the env member using a case-sensitive match.</li> <li><code>Properties.securityRules[0].name</code> references to the name member of the first security rule.</li> <li><code>Properties.securityRules[-1].name</code> references to the name member of the last security rule.</li> <li><code>Properties.securityRules[?@direction == 'Inbound'].name</code> returns the name of any inbound rules.   This will return an array of security rule names.</li> </ul> <p>Notable differences between object paths and JSONPath are:</p> <ul> <li>Member names (properties and keys) are case-insensitive by default.   To perform a case-sensitive match of a member name use a plus selector <code>+</code> in front of the member name.   Some assertions such as <code>HasField</code> provide an option to match case when matching member names.   When this is used, the plus selector perform an case-insensitive match.</li> <li>Quoted member names with single or double quotes are supported with dot selector.   i.e. <code>Properties.'spaced name'</code> is valid.</li> <li>Member names with a dash <code>-</code> are supported without being quoted.   However member names can not start or end with a dash.   i.e. <code>Properties.dashed-name</code> and <code>Properties.'-dashed-name'</code> are valid.</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#apiversion","title":"APIVersion","text":"<p>The <code>APIVersion</code> assertion method checks the field value is a valid date version. A constraint can optionally be provided to require the date version to be within a range.</p> <p>A date version uses the format <code>yyyy-MM-dd</code> (<code>2015-10-01</code>). Additionally an optional string prerelease identifier can be used <code>yyyy-MM-dd-prerelease</code> (<code>2015-10-01-preview.1</code>).</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>constraint</code> (optional) - A version constraint, see below for details of version constrain format.</li> <li><code>includePrerelease</code> (optional) - Determines if prerelease versions are included.   Unless specified this defaults to <code>$False</code>.</li> </ul> <p>The following are supported constraints:</p> <ul> <li><code>version</code> - Must match version exactly. This also accepts the prefix <code>=</code>.<ul> <li>e.g. <code>2015-10-01</code>, <code>=2015-10-01</code></li> </ul> </li> <li><code>&gt;version</code> - Must be greater than version.<ul> <li>e.g. <code>&gt;2015-10-01</code></li> </ul> </li> <li><code>&gt;=version</code> - Must be greater than or equal to version.<ul> <li>e.g. <code>&gt;=2015-10-01</code></li> </ul> </li> <li><code>&lt;version</code> - Must be less than version.<ul> <li>e.g. <code>&lt;2022-03-01</code></li> </ul> </li> <li><code>&lt;=version</code> - Must be less than or equal to version.<ul> <li>e.g. <code>&lt;=2022-03-01</code></li> </ul> </li> </ul> <p>An empty, null or <code>*</code> constraint matches all valid date versions.</p> <p>Multiple constraints can be joined together:</p> <ul> <li>Use a space to separate multiple constraints, each must be true (logical AND).</li> <li>Separates constraint sets with the double pipe <code>||</code>.   Only one constraint set must be true (logical OR).</li> </ul> <p>By example:</p> <ul> <li><code>2014-01-01 || &gt;=2015-10-01 &lt;2022-03-01</code> results in:<ul> <li>Pass: <code>2014-01-01</code>, <code>2015-10-01</code>, <code>2019-06-30</code>, <code>2022-02-01</code>.</li> <li>Fail: <code>2015-01-01</code>, <code>2022-09-01</code>.</li> </ul> </li> </ul> <p>Handling for prerelease versions:</p> <ul> <li>Constraints and versions containing prerelease identifiers are supported.   i.e. <code>&gt;=2015-10-01-preview</code> or <code>2015-10-01-preview</code>.</li> <li>A version containing a prerelease identifer follows similar ordering to semantic versioning.   i.e. <code>2015-10-01-preview</code> &lt; <code>2015-10-01-preview.1</code> &lt; <code>2015-10-01</code> &lt; <code>2022-03-01-preview</code> &lt; <code>2022-03-01</code>.</li> <li>A constraint without a prerelease identifer will only match a stable version by default.   Set <code>includePrerelease</code> to <code>$True</code> to include prerelease versions.   Alternatively use the <code>@pre</code> or <code>@prerelease</code> flag in a constraint.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a version string.</li> <li>The version '{0}' does not match the constraint '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'ValidAPIVersion' {\n    $Assert.APIVersion($TargetObject, 'apiVersion')\n}\n\nRule 'MinimumAPIVersion' {\n    $Assert.APIVersion($TargetObject, 'apiVersion', '&gt;=2015-10-01')\n}\n\nRule 'MinimumAPIVersionWithPrerelease' {\n    $Assert.APIVersion($TargetObject, 'apiVersion', '&gt;=2015-10-01-0', $True)\n}\n\nRule 'MinimumAPIVersionWithFlag' {\n    $Assert.APIVersion($TargetObject, 'apiVersion', '@pre &gt;=2015-10-01-0')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#contains","title":"Contains","text":"<p>The <code>Contains</code> assertion method checks the operand contains the specified string. If the operand is an array of strings, only one string must contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>text</code> - A string or an array of strings to compare the field value with. Only one string must match. When an empty array of strings is specified or text is an empty string, <code>Contains</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'text' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field '{0}' does not contain '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Contains' {\n    $Assert.Contains($TargetObject, 'ResourceGroupName', 'prod')\n    $Assert.Contains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#count","title":"Count","text":"<p>The <code>Count</code> assertion method checks the field value contains the specified number of items. The field value must be an array or collection.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>count</code> - The number of items that the field value must contain.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' has '{1}' items instead of '{2}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Count' {\n    $Assert.Count($TargetObject, 'items', 2)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#endswith","title":"EndsWith","text":"<p>The <code>EndsWith</code> assertion method checks the operand ends with the specified suffix. If the operand is an array of strings, only one string must end with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>suffix</code> - A suffix or an array of suffixes to compare the field value with. Only one suffix must match. When an empty array of suffixes is specified or suffix is an empty string, <code>EndsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'suffix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field '{0}' does not end with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'EndsWith' {\n    $Assert.EndsWith($TargetObject, 'ResourceGroupName', 'eus')\n    $Assert.EndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#fileheader","title":"FileHeader","text":"<p>The <code>FileHeader</code> assertion method checks a file for a comment header. When comparing the file header, the format of line comments are automatically detected by file extension. Single line comments are supported. Multi-line comments are not supported.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a valid file path.</li> <li><code>header</code> - One or more lines of a header to compare with file contents.</li> <li><code>prefix</code> (optional) - An optional comment prefix for each line. By default a comment prefix will automatically detected based on file extension. When set, detection by file extension is skipped.</li> </ul> <p>Prefix detection for line comments is supported with the following file extensions:</p> <ul> <li><code>.bicep</code>, <code>.bicepparam</code>, <code>.cs</code>, <code>.csx</code>, <code>.ts</code>, <code>.tsp</code>, <code>.tsx</code>, <code>.js</code>, <code>.jsx</code>, <code>.fs</code>, <code>.go</code>, <code>.groovy</code>, <code>.php</code>, <code>.cpp</code>, <code>.h</code>, <code>.java</code>, <code>.json</code>, <code>.jsonc</code>, <code>.scala</code>, <code>Jenkinsfile</code> - Use a prefix of (<code>//</code>).</li> <li><code>.editorconfig</code>, <code>.ipynb</code>, <code>.ps1</code>, <code>.psd1</code>, <code>.psm1</code>, <code>.yaml</code>, <code>.yml</code>, <code>.r</code>, <code>.py</code>, <code>.sh</code>, <code>.tf</code>, <code>.tfvars</code>, <code>.toml</code>, <code>.gitignore</code>, <code>.pl</code>, <code>.rb</code>, <code>Dockerfile</code> - Use a prefix of (<code>#</code>).</li> <li><code>.sql</code>, <code>.lau</code> - Use a prefix of (<code>--</code>).</li> <li><code>.bat</code>, <code>.cmd</code> - Use a prefix of (<code>::</code>).</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The file '{0}' does not exist.</li> <li>The header was not set.</li> </ul> <p>Examples:</p> <pre><code>Rule 'FileHeader' {\n    $Assert.FileHeader($TargetObject, 'FullName', @(\n        'Copyright (c) Microsoft Corporation.'\n        'Licensed under the MIT License.'\n    ));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#filepath","title":"FilePath","text":"<p>The <code>FilePath</code> assertion method checks the file exists. Checks use file system case-sensitivity rules.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a file path.</li> <li><code>suffix</code> (optional) - Additional file path suffixes to append. When specified each suffix is combined with the file path. Only one full file path must be a valid file for the assertion method to pass.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The file '{0}' does not exist.</li> </ul> <p>Examples:</p> <pre><code>Rule 'FilePath' {\n    $Assert.FilePath($TargetObject, 'FullName', @('CHANGELOG.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('LICENSE', 'LICENSE.txt'));\n    $Assert.FilePath($TargetObject, 'FullName', @('CODE_OF_CONDUCT.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('CONTRIBUTING.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('SECURITY.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('README.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('.github/CODEOWNERS'));\n    $Assert.FilePath($TargetObject, 'FullName', @('.github/PULL_REQUEST_TEMPLATE.md'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greater","title":"Greater","text":"<p>The <code>Greater</code> assertion method checks the field value is greater than the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &gt; '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Greater' {\n    $Assert.Greater($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greaterorequal","title":"GreaterOrEqual","text":"<p>The <code>GreaterOrEqual</code> assertion method checks the field value is greater or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &gt;= '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'GreaterOrEqual' {\n    $Assert.GreaterOrEqual($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasdefaultvalue","title":"HasDefaultValue","text":"<p>The <code>HasDefaultValue</code> assertion method check that the field does not exist or the field value is set to the default value.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>defaultValue</code> - The expected value if the field exists.</li> </ul> <p>This assertion will pass if:</p> <ul> <li>The field does not exist.</li> <li>The field value is set to <code>defaultValue</code>.</li> </ul> <p>This assertion will fail if:</p> <ul> <li>The field value is set to a value different from <code>defaultValue</code>.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' is set to '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasDefaultValue' {\n    $Assert.HasDefaultValue($TargetObject, 'Properties.osProfile.linuxConfiguration.provisionVMAgent', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfield","title":"HasField","text":"<p>The <code>HasField</code> assertion method checks the object has any of the specified fields.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, only one must exist.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field name.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>Does not exist.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasField' {\n    $Assert.HasField($TargetObject, 'Name')\n    $Assert.HasField($TargetObject, 'tag.Environment', $True)\n    $Assert.HasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfields","title":"HasFields","text":"<p>The <code>HasFields</code> assertion method checks the object has all of the specified fields.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified fields.</li> <li><code>field</code> - The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all fields must exist.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field name.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasFields' {\n    $Assert.HasFields($TargetObject, 'Name')\n    $Assert.HasFields($TargetObject, 'tag.Environment', $True)\n    $Assert.HasFields($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfieldvalue","title":"HasFieldValue","text":"<p>The <code>HasFieldValue</code> assertion method checks the field value of the object is not empty.</p> <p>A field value is empty if any of the following are true:</p> <ul> <li>The field does not exist.</li> <li>The field value is <code>$Null</code>.</li> <li>The field value is an empty array or collection.</li> <li>The field value is an empty string <code>''</code>.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>expectedValue</code> (optional) - Check that the field value is set to a specific value. To check <code>$Null</code> use <code>NullOrEmpty</code> instead. If <code>expectedValue</code> is <code>$Null</code> the field value will not be compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>Does not exist.</li> <li>Is null or empty.</li> <li>Is set to '{0}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasFieldValue' {\n    $Assert.HasFieldValue($TargetObject, 'Name')\n    $Assert.HasFieldValue($TargetObject, 'tag.Environment', 'production')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasjsonschema","title":"HasJsonSchema","text":"<p>The <code>HasJsonSchema</code> assertion method determines if the input object has a <code>$schema</code> property defined. If the <code>$schema</code> property is defined, it must not be empty and match one of the supplied schemas. If a trailing <code>#</code> is specified it is ignored from the <code>$schema</code> property and <code>uri</code> parameter below.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being compared.</li> <li><code>uri</code> - Optional. When specified, the object being compared must have a <code>$schema</code> property set to one of the specified schemas.</li> <li><code>ignoreScheme</code> - Optional. By default, <code>ignoreScheme</code> is <code>$False</code>. When <code>$True</code>, the schema will match if <code>http</code> or <code>https</code> is specified.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The field '$schema' does not exist.</li> <li>The field value '$schema' is not a string.</li> <li>The value of '$schema' is null or empty.</li> <li>None of the specified schemas match '{0}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasFieldValue' {\n    $Assert.HasJsonSchema($TargetObject)\n    $Assert.HasJsonSchema($TargetObject, \"http://json-schema.org/draft-07/schema`#\")\n    $Assert.HasJsonSchema($TargetObject, \"https://json-schema.org/draft-07/schema\", $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#jsonschema","title":"JsonSchema","text":"<p>The <code>JsonSchema</code> assertion method compares the input object against a defined JSON schema.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being compared against the JSON schema.</li> <li><code>uri</code> - A URL or file path to a JSON schema file formatted as UTF-8. Either a file path or URL can be used to specify the location of the schema file.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'uri' is null or empty.</li> <li>The JSON schema '{0}' could not be found.</li> <li>Failed schema validation on {0}. {1}</li> </ul> <p>Examples:</p> <pre><code>Rule 'JsonSchema' {\n    $Assert.JsonSchema($TargetObject, 'tests/PSRule.Tests/FromFile.Json.schema.json')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#in","title":"In","text":"<p>The <code>In</code> assertion method checks the field value is included in a set of values. The field value can either be an integer, float, array, or string. When the field value is an array, only one item must be included in the set.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>values</code> - An array of values that the field value is compared against.   When an empty array is specified, <code>In</code> will always fail.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value.   Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' was not included in the set.</li> </ul> <p>Examples:</p> <pre><code>Rule 'In' {\n    $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'))\n    $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isarray","title":"IsArray","text":"<p>The <code>IsArray</code> assertion method checks the field value is an array type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The field value '{1}' of type {0} is not [array].</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsArray' {\n    # Require Value1 to be an array\n    $Assert.IsArray($TargetObject, 'Value1')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isboolean","title":"IsBoolean","text":"<p>The <code>IsBoolean</code> assertion method checks the field value is a boolean type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not a boolean.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsBoolean' {\n    # Require Value1 to be a boolean\n    $Assert.IsBoolean($TargetObject, 'Value1')\n\n    # Require Value1 to be a boolean or a boolean string\n    $Assert.IsBoolean($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isdatetime","title":"IsDateTime","text":"<p>The <code>IsDateTime</code> assertion method checks the field value is a DateTime type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not a date.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsDateTime' {\n    # Require Value1 to be a DateTime\n    $Assert.IsDateTime($TargetObject, 'Value1')\n\n    # Require Value1 to be a DateTime or a DateTime string\n    $Assert.IsDateTime($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isinteger","title":"IsInteger","text":"<p>The <code>IsInteger</code> assertion method checks the field value is a integer type. The following types are considered integer types <code>int</code>, <code>long</code>, <code>byte</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not an integer.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsInteger' {\n    # Require Value1 to be an integer\n    $Assert.IsInteger($TargetObject, 'Value1')\n\n    # Require Value1 to be an integer or a integer string\n    $Assert.IsInteger($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#islower","title":"IsLower","text":"<p>The <code>IsLower</code> assertion method checks the field value uses only lowercase characters. Non-letter characters are ignored by default and will pass.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>requireLetters</code> (optional) - Require each character to be lowercase letters only. Non-letter characters are ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The value '{0}' does not contain only lowercase characters.</li> <li>The value '{0}' does not contain only letters.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsLower' {\n    # Require Name to be lowercase\n    $Assert.IsLower($TargetObject, 'Name')\n\n    # Require Name to only contain lowercase letters\n    $Assert.IsLower($TargetObject, 'Name', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isnumeric","title":"IsNumeric","text":"<p>The <code>IsNumeric</code> assertion method checks the field value is a numeric type. The following types are considered numeric types <code>int</code>, <code>long</code>, <code>float</code>, <code>byte</code>, <code>double</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert numerical strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not numeric.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsNumeric' {\n    # Require Value1 to be numeric\n    $Assert.IsNumeric($TargetObject, 'Value1')\n\n    # Require Value1 to be numeric or a numerical string\n    $Assert.IsNumeric($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isstring","title":"IsString","text":"<p>The <code>IsString</code> assertion method checks the field value is a string type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not a string.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsString' {\n    # Require Value1 to be a string\n    $Assert.IsString($TargetObject, 'Value1')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isupper","title":"IsUpper","text":"<p>The <code>IsUpper</code> assertion method checks the field value uses only uppercase characters. Non-letter characters are ignored by default and will pass.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>requireLetters</code> (optional) - Require each character to be uppercase letters only. Non-letter characters are ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The value '{0}' does not contain only uppercase characters.</li> <li>The value '{0}' does not contain only letters.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsUpper' {\n    # Require Name to be uppercase\n    $Assert.IsUpper($TargetObject, 'Name')\n\n    # Require Name to only contain uppercase letters\n    $Assert.IsUpper($TargetObject, 'Name', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#less","title":"Less","text":"<p>The <code>Less</code> assertion method checks the field value is less than the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &lt; '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Less' {\n    $Assert.Less($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#lessorequal","title":"LessOrEqual","text":"<p>The <code>LessOrEqual</code> assertion method checks the field value is less or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &lt;= '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'LessOrEqual' {\n    $Assert.LessOrEqual($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#like","title":"Like","text":"<p>The <code>Like</code> assertion method checks the field value matches a specified pattern. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A pattern or an array of patterns to compare the field value with. Only one pattern must match. When an empty array of patterns is specified, <code>Like</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The value '{0}' is not like '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Like' {\n    $Assert.Like($TargetObject, 'ResourceGroupName', 'rg-*')\n    $Assert.Like($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#match","title":"Match","text":"<p>The <code>Match</code> assertion method checks the field value matches a regular expression pattern.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A regular expression pattern to match.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field value '{0}' does not match the pattern '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Match' {\n    $Assert.Match($TargetObject, 'value', '^[a-z]*$')\n    $Assert.Match($TargetObject, 'value', '^[a-z]*$', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcontains","title":"NotContains","text":"<p>The <code>NotContains</code> assertion method checks the operand contains the specified string. This condition fails when any of the specified sub-strings are found. If the operand is an array of strings, this condition fails if any of the strings contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>text</code> - A string or an array of strings to compare the field value with. When an empty array of strings is specified or text is an empty string, <code>NotContains</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'text' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' contains '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotContains' {\n    $Assert.NotContains($TargetObject, 'ResourceGroupName', 'prod')\n    $Assert.NotContains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcount","title":"NotCount","text":"<p>The <code>NotCount</code> assertion method checks the field value does not contain the specified number of items. The field value must be an array or collection.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>count</code> - The number of items that the field value must contain.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' has '{1}' items instead of '{2}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotCount' {\n    $Assert.NotCount($TargetObject, 'items', 2)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notendswith","title":"NotEndsWith","text":"<p>The <code>NotEndsWith</code> assertion method checks the operand ends with the specified suffix. This condition fails when any of the specified sub-strings are found at the end of the operand. If the operand is an array of strings, this condition fails if any of the strings ends with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>suffix</code> - A suffix or an array of suffixes to compare the field value with. When an empty array of suffixes is specified or suffix is an empty string, <code>NotEndsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'suffix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' ends with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotEndsWith' {\n    $Assert.NotEndsWith($TargetObject, 'ResourceGroupName', 'eus')\n    $Assert.NotEndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nothasfield","title":"NotHasField","text":"<p>The <code>NotHasField</code> assertion method checks the object does not have any of the specified fields.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all must not exist.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field name.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' exists.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotHasField' {\n    $Assert.NotHasField($TargetObject, 'Name')\n    $Assert.NotHasField($TargetObject, 'tag.Environment', $True)\n    $Assert.NotHasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notin","title":"NotIn","text":"<p>The <code>NotIn</code> assertion method checks the field value is not in a set of values. The field value can either be an integer, array, float, or string. When the field value is an array, none of the items must be included in the set. If the field does not exist at all, it is not in the set and passes. To check the field exists combine this assertion method with <code>HasFieldValue</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>values</code> - An array values that the field value is compared against. When an empty array is specified, <code>NotIn</code> will always pass.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field value '{0}' was in the set.</li> </ul> <p>Examples:</p> <pre><code>Rule 'In' {\n    $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'))\n    $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notlike","title":"NotLike","text":"<p>The <code>NotLike</code> assertion method checks the field value matches a specified pattern. This condition fails when any of the specified patterns match the field value. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A pattern or an array of patterns to compare the field value with. When an empty array of pattens is specified, <code>NotLike</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' is like '{1}'</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotLike' {\n    $Assert.NotLike($TargetObject, 'ResourceGroupName', 'rg-*')\n    $Assert.NotLike($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notmatch","title":"NotMatch","text":"<p>The <code>NotMatch</code> assertion method checks the field value does not match a regular expression pattern. If the field does not exist at all, it does not match and passes. To check the field exists combine this assertion method with <code>HasFieldValue</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A regular expression pattern to match.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field value '{0}' is not a string.</li> <li>The field value '{0}' matches the pattern '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotMatch' {\n    $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$')\n    $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notnull","title":"NotNull","text":"<p>The <code>NotNull</code> assertion method checks the field value of the object is not null.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotNull' {\n    $Assert.NotNull($TargetObject, 'Name')\n    $Assert.NotNull($TargetObject, 'tag.Environment')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notstartswith","title":"NotStartsWith","text":"<p>The <code>NotStartsWith</code> assertion method checks the operand starts with the specified prefix. This condition fails when any of the specified sub-strings are found at the start of the operand. If the operand is an array of strings, this condition fails if any of the strings start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>prefix</code> - A prefix or an array of prefixes to compare the field value with. When an empty array of prefixes is specified or prefix is an empty string, <code>NotStartsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' starts with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotStartsWith' {\n    $Assert.NotStartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n    $Assert.NotStartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notwithinpath","title":"NotWithinPath","text":"<p>The <code>NotWithinPath</code> assertion method checks the file is not within a specified path. Checks use file system case-sensitivity rules by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a file path. When the field is <code>InputFileInfo</code> or <code>FileInfo</code>, PSRule will automatically resolve the file path.</li> <li><code>path</code> - An array of one or more directory paths to check. Only one path must match.</li> <li><code>caseSensitive</code> (optional) - Determines if case-sensitive path matching is used. This can be set to <code>$True</code> or <code>$False</code>. When not set or <code>$Null</code>, the case-sensitivity rules of the working path file system will be used.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'path' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The file '{0}' is within the path '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotWithinPath' {\n    # The file must not be within either policy/ or security/ sub-directories.\n    $Assert.NotWithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#null","title":"Null","text":"<p>The <code>Null</code> assertion method checks the field value of the object is null.</p> <p>A field value is null if any of the following are true:</p> <ul> <li>The field does not exist.</li> <li>The field value is <code>$Null</code>.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field value '{0}' is not null.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Null' {\n    $Assert.Null($TargetObject, 'NotField')\n    $Assert.Null($TargetObject, 'tag.NullField')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nullorempty","title":"NullOrEmpty","text":"<p>The <code>NullOrEmpty</code> assertion method checks the field value of the object is null or empty.</p> <p>A field value is null or empty if any of the following are true:</p> <ul> <li>The field does not exist.</li> <li>The field value is <code>$Null</code>.</li> <li>The field value is an empty array or collection.</li> <li>The field value is an empty string <code>''</code>.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' is not empty.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NullOrEmpty' {\n    $Assert.NullOrEmpty($TargetObject, 'Name')\n    $Assert.NullOrEmpty($TargetObject, 'tag.Environment')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#typeof","title":"TypeOf","text":"<p>The <code>TypeOf</code> assertion method checks the field value is a specified type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>type</code> - One or more specified types to check. The field value only has to match a single type of more than one type is specified.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'type' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The field value '{2}' of type {1} is not {0}.</li> </ul> <p>Examples:</p> <pre><code>Rule 'TypeOf' {\n    # Require Value1 to be [int]\n    $Assert.TypeOf($TargetObject, 'Value1', [int])\n\n    # Require Value1 to be [int] or [long]\n    $Assert.TypeOf($TargetObject, 'Value1', @([int], [long]))\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#setof","title":"SetOf","text":"<p>The <code>SetOf</code> assertion method checks the field value only includes all of the specified values. The field value must be an array or collection. Specified values can be included in the field value in any order.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>values</code> - An array of values that the field value is compared against.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value.   Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' did not contain '{1}'.</li> <li>The field '{0}' has '{1}' items instead of '{2}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Subset' {\n    $Assert.SetOf($TargetObject, 'zones', @('1', '2', '3'))\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#startswith","title":"StartsWith","text":"<p>The <code>StartsWith</code> assertion method checks the operand starts with the specified prefix. If the operand is an array of strings, only one string must start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>prefix</code> - A prefix or an array of prefixes to compare the field value with. Only one prefix must match. When an empty array of prefixes is specified or prefix is an empty string, <code>StartsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field '{0}' does not start with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'StartsWith' {\n    $Assert.StartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n    $Assert.StartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#subset","title":"Subset","text":"<p>The <code>Subset</code> assertion method checks the field value includes all of the specified values. The field value may also contain additional values that are not specified in the <code>values</code> parameter. The field value must be an array or collection. Specified values can be included in the field value in any order.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>values</code> - An array of values that the field value is compared against.   When an empty array is specified, <code>Subset</code> will always pass.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value.   Case is ignored by default.</li> <li><code>unique</code> (optional) - A boolean value that indicates if the items must be unique.   When <code>true</code> the field value must not contain duplicate items.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' did not contain '{1}'.</li> <li>The field '{0}' included multiple instances of '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Subset' {\n    $Assert.Subset($TargetObject, 'logs', @('cluster-autoscaler', 'kube-apiserver', 'kube-scheduler'), $True, $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#version","title":"Version","text":"<p>The <code>Version</code> assertion method checks the field value is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>constraint</code> (optional) - A version constraint, see below for details of version constrain format.</li> <li><code>includePrerelease</code> (optional) - Determines if prerelease versions are included. Unless specified this defaults to <code>$False</code>.</li> </ul> <p>The following are supported constraints:</p> <ul> <li><code>version</code> - Must match version exactly. This also accepts the following prefixes; <code>=</code>, <code>v</code>, <code>V</code>.<ul> <li>e.g. <code>1.2.3</code>, <code>=1.2.3</code></li> </ul> </li> <li><code>&gt;version</code> - Must be greater than version.<ul> <li>e.g. <code>&gt;1.2.3</code></li> </ul> </li> <li><code>&gt;=version</code> - Must be greater than or equal to version.<ul> <li>e.g. <code>&gt;=1.2.3</code></li> </ul> </li> <li><code>&lt;version</code> - Must be less than version.<ul> <li>e.g. <code>&lt;1.2.3</code></li> </ul> </li> <li><code>&lt;=version</code> - Must be less than or equal to version.<ul> <li>e.g. <code>&lt;=1.2.3</code></li> </ul> </li> <li><code>^version</code> - Compatible with version.<ul> <li>e.g. <code>^1.2.3</code> - <code>&gt;=1.2.3</code>, <code>&lt;2.0.0</code></li> </ul> </li> <li><code>~version</code> - Approximately equivalent to version<ul> <li>e.g. <code>~1.2.3</code> - <code>&gt;=1.2.3</code>, <code>&lt;1.3.0</code></li> </ul> </li> </ul> <p>An empty, null or <code>*</code> constraint matches all valid semantic versions.</p> <p>Multiple constraints can be joined together:</p> <ul> <li>Use a space to separate multiple constraints, each must be true (logical AND).</li> <li>Separates constraint sets with the double pipe <code>||</code>. Only one constraint set must be true (logical OR).</li> </ul> <p>By example:</p> <ul> <li><code>1.2.3 || &gt;=3.4.5 &lt;5.0.0</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>3.4.5</code>, <code>3.5.0</code>, <code>4.9.9</code>.</li> <li>Fail: <code>3.0.0</code>, <code>5.0.0</code>.</li> </ul> </li> </ul> <p>Handling for prerelease versions:</p> <ul> <li>Constraints and versions containing prerelease identifiers are supported. i.e. <code>&gt;=1.2.3-build.1</code> or <code>1.2.3-build.1</code>.</li> <li>A version containing a prerelease identifer follows semantic versioning rules. i.e. <code>1.2.3-alpha</code> &lt; <code>1.2.3-alpha.1</code> &lt; <code>1.2.3-alpha.beta</code> &lt; <code>1.2.3-beta</code> &lt; <code>1.2.3-beta.2</code> &lt; <code>1.2.3-beta.11</code> &lt; <code>1.2.3-rc.1</code> &lt; <code>1.2.3</code>.</li> <li>A constraint without a prerelease identifer will only match a stable version by default. Set <code>includePrerelease</code> to <code>$True</code> to include prerelease versions.</li> <li>Constraints with a prerelease identifer will only match:<ul> <li>Matching prerelease versions of the same major.minor.patch version by default. Set <code>includePrerelease</code> to <code>$True</code> to include prerelease versions of all matching versions. Alternatively use the <code>@pre</code> or <code>@prerelease</code> flag in a constraint.</li> <li>Matching stable versions.</li> </ul> </li> </ul> <p>By example:</p> <ul> <li><code>&gt;=1.2.3</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>9.9.9</code>.</li> <li>Fail: <code>1.2.3-build.1</code>, <code>9.9.9-build.1</code>.</li> </ul> </li> <li><code>&gt;=1.2.3-0</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>1.2.3-build.1</code>, <code>9.9.9</code>.</li> <li>Fail: <code>9.9.9-build.1</code>.</li> </ul> </li> <li><code>&lt;1.2.3</code> results in:<ul> <li>Pass: <code>1.2.2</code>, <code>1.0.0</code>.</li> <li>Fail: <code>1.0.0-build.1</code>, <code>1.2.3-build.1</code>.</li> </ul> </li> <li><code>&lt;1.2.3-0</code> results in:<ul> <li>Pass: <code>1.2.2</code>, <code>1.0.0</code>.</li> <li>Fail: <code>1.0.0-build.1</code>, <code>1.2.3-build.1</code>.</li> </ul> </li> <li><code>@pre &gt;=1.2.3</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>9.9.9</code>, <code>9.9.9-build.1</code></li> <li>Fail: <code>1.2.3-build.1</code>.</li> </ul> </li> <li><code>@pre &gt;=1.2.3-0</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>1.2.3-build.1</code>, <code>9.9.9</code>, <code>9.9.9-build.1</code>.</li> </ul> </li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a version string.</li> <li>The version '{0}' does not match the constraint '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'ValidVersion' {\n    $Assert.Version($TargetObject, 'version')\n}\n\nRule 'MinimumVersion' {\n    $Assert.Version($TargetObject, 'version', '&gt;=1.2.3')\n}\n\nRule 'MinimumVersionWithPrerelease' {\n    $Assert.Version($TargetObject, 'version', '&gt;=1.2.3-0', $True)\n}\n\nRule 'MinimumVersionWithFlag' {\n    $Assert.Version($TargetObject, 'version', '@pre &gt;=1.2.3-0')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#withinpath","title":"WithinPath","text":"<p>The <code>WithinPath</code> assertion method checks if the file path is within a required path. Checks use file system case-sensitivity rules by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a file path. When the field is <code>InputFileInfo</code> or <code>FileInfo</code>, PSRule will automatically resolve the file path.</li> <li><code>path</code> - An array of one or more directory paths to check. Only one path must match.</li> <li><code>caseSensitive</code> (optional) - Determines if case-sensitive path matching is used. This can be set to <code>$True</code> or <code>$False</code>. When not set or <code>$Null</code>, the case-sensitivity rules of the working path file system will be used.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'path' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The file '{0}' is not within the path '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'WithinPath' {\n    # Require the file to be within either policy/ or security/ sub-directories.\n    $Assert.WithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#advanced-usage","title":"Advanced usage","text":"<p>The <code>AssertResult</code> object returned from assertion methods:</p> <ul> <li>Handles pass/ fail conditions and collection of reason information.</li> <li>Allows rules to implement their own handling or forward it up the stack to affect the rule outcome.</li> </ul> <p>The following properties are available:</p> <ul> <li><code>Result</code> - Either <code>$True</code> (Pass) or <code>$False</code> (Fail).</li> </ul> <p>The following methods are available:</p> <ul> <li><code>AddReason(&lt;string&gt; text)</code> - Can be used to append additional reasons to the result.   A reason can only be set if the assertion failed.   Reason text should be localized before calling this method.   Localization can be done using the <code>$LocalizedData</code> automatic variable.</li> <li><code>WithReason(&lt;string&gt; text, &lt;bool&gt; replace)</code> - Can be used to append or replace reasons on the result.   In addition, <code>WithReason</code> can be chained.</li> <li><code>Reason(&lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason on the results with a formatted string.   This method can be chained.   For usage see examples below.</li> <li><code>ReasonFrom(&lt;string&gt; path, &lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason on the results with a formatted string.   Path specifies the object path that affected the reason.   This method can be chained.   For usage see examples below.</li> <li><code>ReasonIf(&lt;bool&gt; condition, &lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason if the condition is true.   This method can be chained, similar to <code>Reason</code>.</li> <li><code>ReasonIf(&lt;string&gt; path, &lt;bool&gt; condition, &lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason if the condition is true.   This method can be chained, similar to <code>ReasonFrom</code>.</li> <li><code>PathPrefix(&lt;string&gt; path)</code> - Adds a path prefix to any reasons.   This method can be chained.   For usage see examples below.</li> <li><code>GetReason()</code> - Gets any reasons currently associated with the failed result.</li> <li><code>Complete()</code> - Returns <code>$True</code> (Pass) or <code>$False</code> (Fail) to the rule record.   If the assertion failed, any reasons are automatically added to the rule record.   To read the result without adding reason to the rule record use the <code>Result</code> property.</li> <li><code>Ignore()</code> - Ignores the result. Nothing future is returned and any reasons are cleared.   Use this method when implementing custom handling.</li> </ul> <p>Use of <code>Complete</code> is optional, uncompleted results are automatically completed after the rule has executed. Uncompleted results may return reasons out of sequence.</p> <p>Using these advanced methods is not supported in rule script pre-conditions.</p> <p>In this example, <code>Complete</code> is used to find the first field with an empty value.</p> <pre><code>Rule 'Assert.HasFieldValue' {\n    $Assert.HasFieldValue($TargetObject, 'Name').Complete() -and\n        $Assert.HasFieldValue($TargetObject, 'Type').Complete() -and\n        $Assert.HasFieldValue($TargetObject, 'Value').Complete()\n}\n</code></pre> <p>In this example, the built-in reason is replaced with a custom reason, and immediately returned. The reason text is automatically formatted with any parameters provided.</p> <pre><code>Rule 'Assert.HasCustomValue' {\n    $Assert.\n        HasDefaultValue($TargetObject, 'value', 'test').\n        Reason('The field {0} is using a non-default value: {1}', 'value', $TargetObject.value)\n\n    # With localized string\n    $Assert.\n        HasDefaultValue($TargetObject, 'value', 'test').\n        Reason($LocalizedData.NonDefaultValue, 'value', $TargetObject.value)\n}\n</code></pre> <p>In this example, the built-in reason has a path prefix added to any reasons.</p> <pre><code>Rule 'Assert.ChildHasFieldValue' {\n    $items = @($TargetObject.items)\n    for ($i = 0; $i -lt $items.Length; $i++) {\n        $Assert.HasFieldValue($items[$i], 'Name').PathPrefix(\"items[$i]\")\n    }\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#downstream-issues","title":"Downstream issues","text":"<p>Before PSRule performs analysis external tools or rules modules may have already performed analysis. Issues identified by downstream tools can be consumed by PSRule using the <code>_PSRule.issue</code> property. If a <code>_PSRule</code> property exists with <code>issue</code> sub-property PSRule will consume <code>issue</code> as an array of issues.</p> <p>Each issue has the following properties:</p> <ul> <li><code>type</code> - The issue type.   Issues are filtered by type.</li> <li><code>name</code> - The name of a specific issue.</li> <li><code>message</code> - The reason message for the issue.</li> </ul> <p>To get issues for an object use the <code>Get</code> or <code>Any</code> methods.</p> <pre><code># Get an array of all issues for the current object.\n$PSRule.Issue.Get();\n\n# Get an array of issues of a specific type.\n$PSRule.Issue.Get('CustomIssue');\n\n# Return true of any issues exist.\n$PSRule.Issue.Any();\n\n# Return true of any issues of a specific type exist.\n$PSRule.Issue.Any('CustomIssue');\n</code></pre> <p>For example:</p> <pre><code># Synopsis: Fail if the object has any 'PSRule.Rules.Azure.Parameter.Insecure' issues.\nRule 'IssueReportTest' {\n    $Assert.Create($PSRule.Issue.Get('PSRule.Rules.Azure.Parameter.Insecure'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#authoring-assertion-methods","title":"Authoring assertion methods","text":"<p>The following built-in helper methods are provided for working with <code>$Assert</code> when authoring new assertion methods:</p> <ul> <li><code>Create(&lt;bool&gt; condition, &lt;string&gt; reason, params &lt;object[]&gt; args)</code> - Returns a result either pass or fail assertion result.   Additional arguments can be provided to format the custom reason string.</li> <li><code>Create(&lt;TargetIssueInfo[]&gt;)</code> - Returns a result based on reported downstream issues.</li> <li><code>Pass()</code> - Returns a pass assertion result.</li> <li><code>Fail()</code> - Results a fail assertion result.</li> <li><code>Fail(&lt;string&gt; reason, params &lt;object[]&gt; args)</code> - Results a fail assertion result with a custom reason.   Additional arguments can be provided to format the custom reason string.</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#aggregating-assertion-methods","title":"Aggregating assertion methods","text":"<p>The following built-in helper methods are provided for aggregating assertion results:</p> <ul> <li><code>AnyOf(&lt;AssertResult[]&gt; results)</code> - Results from assertion methods are aggregated into a single result.   If any result is a pass, the result is a pass.   If all results are fails, the result is a fail and any reasons are added to the result.   If no results are provided, the result is a fail.</li> <li><code>AllOf(&lt;AssertResult[]&gt; results)</code> - Results from assertion methods are aggregated into a single result.   If all results are passes, the result is a pass.   If any result is a fail, the result is a fail and any reasons are added to the result.   If no results are provided, the result is a fail.</li> </ul> <p>For example:</p> <pre><code>Rule 'Assert.HasFieldValue' {\n    $Assert.AllOf(\n        $Assert.HasFieldValue($TargetObject, 'Name'),\n        $Assert.HasFieldValue($TargetObject, 'Type'),\n        $Assert.HasFieldValue($TargetObject, 'Value')\n    )\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#links","title":"Links","text":"<ul> <li>about_PSRule_Variables</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/","title":"Badges","text":"<p>Describes using the badge API with PSRule.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. The badge API can be used to create badges within a convention.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-the-api","title":"Using the API","text":"<p>PSRule provides the <code>$PSRule</code> built-in variable that exposes the badge API. By using the <code>$PSRule.Badges.Create</code> method you can create a standard or custom badge.</p> <p>The create method provides the following overloads:</p> <pre><code>// Create a badge for the worst case of an analyzed object.\nIBadge Create(InvokeResult result);\n\n// Create a badge for the worst case of all analyzed objects.\nIBadge Create(IEnumerable&lt;InvokeResult&gt; result);\n\n// Create a custom badge.\nIBadge Create(string title, BadgeType type, string label);\n</code></pre> <p>A badge once created can be read as a string or written to disk with the following methods:</p> <pre><code>// Get the badge as SVG text content.\nstring ToSvg();\n\n// Write the SVG badge content directly to disk.\nvoid ToFile(string path);\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#defining-conventions","title":"Defining conventions","text":"<p>To define a convention, add a <code>Export-PSRuleConvention</code> block within a <code>.Rule.ps1</code> file. The <code>.Rule.ps1</code> must be in an included path or module with <code>-Path</code> or <code>-Module</code>.</p> <p>The <code>Export-PSRuleConvention</code> block works similar to the <code>Rule</code> block. Each convention must have a unique name. Currently the badge API support creating badges in the <code>-End</code> block.</p> <p>For example:</p> <pre><code># Synopsis: A convention that generates a badge for an aggregate result.\nExport-PSRuleConvention 'Local.Aggregate' -End {\n    $PSRule.Badges.Create($PSRule.Output).ToFile('out/badges/aggregate.svg');\n}\n</code></pre> <pre><code># Synopsis: A convention that generates a custom badge.\nExport-PSRuleConvention 'Local.CustomBadge' -End {\n    $PSRule.Badges.Create('PSRule', [PSRule.Badges.BadgeType]::Success, 'OK').ToFile('out/badges/custom.svg');\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-conventions","title":"Using conventions","text":"<p>A convention can be included by using the <code>-Convention</code> parameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:</p> <pre><code>Invoke-PSRule -Convention 'Local.Aggregate';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/","title":"Baselines","text":"<p>Describes usage of baselines within PSRule.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#description","title":"Description","text":"<p>PSRule lets you define a baseline. A baseline includes a set of rule and configuration options that are used for evaluating objects.</p> <p>The following baseline options can be configured:</p> <ul> <li>Binding.Field</li> <li>Binding.IgnoreCase</li> <li>Binding.NameSeparator</li> <li>Binding.PreferTargetInfo</li> <li>Binding.TargetName</li> <li>Binding.TargetType</li> <li>Binding.UseQualifiedName</li> <li>Configuration</li> <li>Rule.Include</li> <li>Rule.IncludeLocal</li> <li>Rule.Exclude</li> <li>Rule.Tag</li> </ul> <p>Baseline options can be:</p> <ul> <li>Included as a baseline spec within a YAML or JSON file.<ul> <li>When using this method, multiple baseline specs can be defined within the same YAML/JSON file.</li> <li>Each YAML baseline spec is separated using <code>---</code>.</li> <li>Each JSON baseline spec is separated by JSON objects in a JSON array.</li> </ul> </li> <li>Set within a workspace options file like <code>ps-rule.yaml</code> or <code>ps-rule.json</code>.<ul> <li>Only a single baseline can be specified.</li> <li>See about_PSRule_Options for details on using this method.</li> </ul> </li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#baseline-specs","title":"Baseline specs","text":"<p>YAML baseline specs are saved within a YAML file with a <code>.Rule.yaml</code> or <code>.Rule.yml</code> extension, for example <code>Baseline.Rule.yaml</code>.</p> <p>JSON baseline specs are saved within a file with a <code>.Rule.json</code> or <code>.Rule.jsonc</code> extension, for example <code>Baseline.Rule.json</code>. Use <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>To define a YAML baseline spec use the following structure:</p> <pre><code>---\n# Synopsis: &lt;synopsis&gt;\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: &lt;name&gt;\n  annotations: { }\nspec:\n  # One or more baseline options\n  binding: { }\n  rule: { }\n  configuration: { }\n</code></pre> <p>For example:</p> <pre><code>---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: Baseline1\nspec:\n  binding:\n    field:\n      id:\n      - ResourceId\n    targetName:\n    - Name\n    - ResourceName\n    - ResourceGroupName\n    targetType:\n    - ResourceType\n  rule:\n    include:\n    - Rule1\n    - Rule2\n  configuration:\n    allowedLocations:\n    - 'Australia East'\n    - 'Australia South East'\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: Baseline2\nspec:\n  binding:\n    targetName:\n    - Name\n    - ResourceName\n    - ResourceGroupName\n    targetType:\n    - ResourceType\n  rule:\n    include:\n    - Rule1\n    - Rule3\n  configuration:\n    allowedLocations:\n    - 'Australia East'\n</code></pre> <p>To define a JSON baseline spec use the following structure:</p> <pre><code>[\n  {\n    // Synopsis: &lt;synopsis&gt;\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"&lt;name&gt;\",\n      \"annotations\": {}\n    },\n    \"spec\": {\n      \"binding\": {},\n      \"rule\": {},\n      \"configuration\": {}\n    }\n  }\n]\n</code></pre> <p>For example:</p> <pre><code>[\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"Baseline1\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"field\": {\n          \"id\": [\n            \"ResourceId\"\n          ]\n        },\n        \"targetName\": [\n          \"Name\",\n          \"ResourceName\",\n          \"ResourceGroupName\"\n        ],\n        \"targetType\": [\n          \"ResourceType\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"Rule1\",\n          \"Rule2\"\n        ]\n      },\n      \"configuration\": {\n        \"allowedLocations\": [\n          \"Australia East\",\n          \"Australia South East\"\n        ]\n      }\n    }\n  },\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"Baseline2\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"targetName\": [\n          \"Name\",\n          \"ResourceName\",\n          \"ResourceGroupName\"\n        ],\n        \"targetType\": [\n          \"ResourceType\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"Rule1\",\n          \"Rule3\"\n        ]\n      },\n      \"configuration\": {\n        \"allowedLocations\": [\n          \"Australia East\"\n        ]\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#baseline-scopes","title":"Baseline scopes","text":"<p>When baseline options are set, PSRule uses the following order to determine precedence.</p> <ol> <li>Parameter - <code>-Name</code> and <code>-Tag</code>.</li> <li>Explicit - A named baseline specified with <code>-Baseline</code>.</li> <li>Workspace - Included in <code>ps-rule.yaml</code> or specified on the command line with <code>-Option</code>.</li> <li>Module - A baseline object included in a <code>.Rule.yaml</code> or <code>.Rule.json</code> file.</li> </ol> <p>After precedence is determined, baselines are merged and null values are ignored, such that:</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#annotations","title":"Annotations","text":"<p>Additional baseline annotations can be provided as key/ value pairs. Annotations can be used to provide additional information that is available in <code>Get-PSRuleBaseline</code> output.</p> <p>The following reserved annotation exists:</p> <ul> <li><code>obsolete</code> - Marks the baseline as obsolete when set to <code>true</code>. PSRule will generate a warning when an obsolete baseline is used.</li> </ul> <p>YAML example:</p> <pre><code>---\n# Synopsis: This is an example baseline that is obsolete\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: ObsoleteBaseline\n  annotations:\n    obsolete: true\nspec: { }\n</code></pre> <p>JSON example:</p> <pre><code>[\n  {\n    // Synopsis: This is an example baseline that is obsolete\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"ObsoleteBaseline\",\n      \"annotations\": {\n        \"obsolete\": true\n      }\n    },\n    \"spec\": {}\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselineruleyaml","title":"Example Baseline.Rule.yaml","text":"<pre><code># Example Baseline.Rule.yaml\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline1\nspec:\n  binding:\n    targetName:\n    - AlternateName\n    targetType:\n    - kind\n  rule:\n    include:\n    - 'WithBaseline'\n  configuration:\n    key1: value1\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline2\nspec:\n  binding:\n    targetName:\n    - AlternateName\n    targetType:\n    - kind\n  rule:\n    include:\n    - 'WithBaseline'\n  configuration:\n    key1: value1\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselinerulejson","title":"Example Baseline.Rule.json","text":"<pre><code>// Example Baseline.Rule.json\n\n[\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"TestBaseline1\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"targetName\": [\n          \"AlternateName\"\n        ],\n        \"targetType\": [\n          \"kind\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"WithBaseline\"\n        ]\n      },\n      \"configuration\": {\n        \"key1\": \"value1\"\n      }\n    }\n  },\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"TestBaseline2\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"targetName\": [\n          \"AlternateName\"\n        ],\n        \"targetType\": [\n          \"kind\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"WithBaseline\"\n        ]\n      },\n      \"configuration\": {\n        \"key1\": \"value1\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/","title":"Conventions","text":"<p>Describes PSRule Conventions including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. Each convention, hooks into one or more places within the pipeline.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-conventions","title":"Using conventions","text":"<p>A convention can be included by using the <code>-Convention</code> parameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:</p> <pre><code>Invoke-PSRule -Convention 'ExampleConvention';\n</code></pre> <p>If multiple conventions are specified in an array, all are executed in they are specified. As a result, the convention specified last may override state set by earlier conventions.</p> <pre><code>Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#defining-conventions","title":"Defining conventions","text":"<p>To define a convention, add a <code>Export-PSRuleConvention</code> block within a <code>.Rule.ps1</code> file. The <code>.Rule.ps1</code> must be in an included path or module with <code>-Path</code> or <code>-Module</code>.</p> <p>The <code>Export-PSRuleConvention</code> block works similar to the <code>Rule</code> block. Each convention must have a unique name. For example:</p> <pre><code># Synopsis: An example convention.\nExport-PSRuleConvention 'ExampleConvention' {\n    # Add code here\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#initialize-begin-process-end-blocks","title":"Initialize Begin Process End blocks","text":"<p>Conventions define four executable blocks <code>Initialize</code>, <code>Begin</code>, <code>Process</code>, <code>End</code> similar to a PowerShell function. Each block is injected in a different part of the pipeline as follows:</p> <ul> <li><code>Initialize</code> occurs once at the beginning of the pipeline.   Use <code>Initialize</code> to perform any initialization required by the convention.</li> <li><code>Begin</code> occurs once per object before the any rules are executed.   Use <code>Begin</code> blocks to perform expansion, set data, or alter the object before rules are processed.</li> <li><code>Process</code> occurs once per object after all rules are executed.   Use <code>Process</code> blocks to perform per object tasks such as generate badges.</li> <li><code>End</code> occurs only once after all objects have been processed.   Use <code>End</code> blocks to upload results to an external service.</li> </ul> <p>Convention block limitations:</p> <ul> <li><code>Initialize</code> can not use automatic variables except <code>$PSRule</code>.   Most methods and properties of <code>$PSRule</code> are not available in <code>Initialize</code>.</li> <li><code>Begin</code> and <code>Process</code> can not use rule specific variables such as <code>$Rule</code>.   These blocks are executed outside of the context of a single rule.</li> <li><code>End</code> can not use automatic variables except <code>$PSRule</code>.   Most methods and properties of <code>$PSRule</code> are not available in <code>End</code>.</li> </ul> <p>By default, the <code>Process</code> block used. For example:</p> <pre><code># Synopsis: The default { } executes the process block\nExport-PSRuleConvention 'ExampleConvention' {\n    # Process block\n}\n\n# Synopsis: With optional -Process parameter name\nExport-PSRuleConvention 'ExampleConvention' -Process {\n    # Process block\n}\n</code></pre> <p>To use <code>Initialize</code>, <code>Begin</code>, or <code>End</code> explicitly add these blocks. For example:</p> <pre><code>Export-PSRuleConvention 'ExampleConvention' -Process {\n    # Process block\n} -Begin {\n    # Begin block\n} -End {\n    # End block\n} -Initialize {\n    # Initialize block\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#including-with-options","title":"Including with options","text":"<p>Conventions can be included by name within options in addition to using the <code>-Convention</code> parameter. To specify a convention within YAML options use the following:</p> ps-rule.yaml<pre><code>convention:\n  include:\n  - 'ExampleConvention1'\n  - 'ExampleConvention2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-within-modules","title":"Using within modules","text":"<p>Conventions can be shipped within a module using the same packaging and distribution process as rules. Additionally, conventions shipped within a module can be automatically included. By default, PSRule does not include conventions shipped within a module. To use a convention included in a module use the <code>-Convention</code> parameter or options configuration.</p> <p>A module can automatically include a convention by specifying the convention by name in module configuration. For example:</p> Config.Rule.yaml<pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: ExampleModule\nspec:\n  convention:\n    include:\n    - 'ExampleConvention1'\n    - 'ExampleConvention2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#execution-order","title":"Execution order","text":"<p>Conventions are executed in the order they are specified. This is true for <code>Initialize</code>, <code>Begin</code>, <code>Process</code>, and <code>End</code> blocks. i.e. In the following example <code>ExampleConvention1</code> is execute before <code>ExampleConvention2</code>.</p> <pre><code>Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\n</code></pre> <p>When conventions are specified from multiple locations PSRule orders conventions as follows:</p> <ol> <li>Using <code>-Convention</code> parameter.</li> <li>PSRule options.</li> <li>Module configuration.</li> </ol>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/","title":"Documentation","text":"<p>Describes usage of documentation within PSRule.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#description","title":"Description","text":"<p>PSRule includes a built-in documentation system that provide culture specific help and metadata for resources. Documentation is composed of markdown files that can be optionally shipped with a module.</p> <p>When markdown documentation is defined, this content will be used instead of inline synopsis comments. Markdown documentation is supported for rules and suppression groups.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#getting-documentation","title":"Getting documentation","text":"<p>To get documentation for a rule use the <code>Get-PSRuleHelp</code> cmdlet.</p> <p>For example:</p> <pre><code>Get-PSRuleHelp &lt;rule-name&gt;\n</code></pre> <p>Each rule can include the following documentation:</p> <ul> <li>Annotations - Additional metadata included in results.</li> <li>Synopsis - A brief description on the intended purpose of the rule.</li> <li>Description - A detailed description on the intended purpose of the rule.</li> <li>Recommendation - A detailed explanation of the requirements to pass the rule.</li> <li>Notes - Any additional information or configuration options.</li> <li>Links - Any links to external references.</li> </ul> <p>See cmdlet help for detailed information on the <code>Get-PSRuleHelp</code> cmdlet.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#online-help","title":"Online help","text":"<p>Rule documentation may optionally include a link to an online version. When included, the <code>-Online</code> parameter can be used to open the online version in the default web browser.</p> <p>For example:</p> <pre><code>Get-PSRuleHelp &lt;rule-name&gt; -Online\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-rules","title":"Creating documentation for rules","text":"<p>Rule documentation is composed of markdown files, one per rule. When creating rules for more then one culture, a separate markdown file is created per rule per culture.</p> <p>The markdown files for each rule is automatically discovered based on naming convention.</p> <p>Markdown is saved in a file with the same filename as the rule name with the <code>.md</code> extension. The file name should match the same case exactly, with a lower case extension.</p> <p>As an example, the <code>storageAccounts.UseHttps.md</code> markdown file would be created.</p> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre> <p>The markdown of each file uses following structure.</p> <pre><code>---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n\n\n{{ A brief summary of the rule }}\n\n## Description\n\n{{ A detailed description of the rule }}\n\n## Recommendation\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## Notes\n\n{{ Additional information or configuration options }}\n\n## Links\n\n{{ Links to external references }}\n</code></pre> <p>Optionally, one or more annotations formatted as YAML key value pairs can be included. i.e. <code>severity: Critical</code></p> <p>Additional sections such as <code>EXAMPLES</code> can be included although are not exposed with <code>Get-PSRuleHelp</code>.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-suppression-groups","title":"Creating documentation for suppression groups","text":"<p>Suppression groups support documentation similar to rules that allows a synopsis to be defined. Other sections can be added to the markdown content, but are ignored. Set the synopsis in markdown to allow a culture specific message to be displayed.</p> <p>The markdown of each file uses following structure.</p> <pre><code>---\n{{ Annotations }}\n---\n\n# {{ Name of suppression group }}\n\n\n\n{{ A brief summary of the suppression group }}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#storing-markdown-files","title":"Storing markdown files","text":"<p>The location PSRule uses to find markdown documentation depends on how the rules/ resources are packaged. In each case, documentation will be in a culture <code>/&lt;culture&gt;/</code>specific subdirectory. Resources can be either shipped as part of a module, or standalone.</p> <ul> <li>When resources are standalone, the culture subdirectory is relative to the <code>*.Rule.*</code> file.</li> <li>When packaged in a module, the culture subdirectory is relative to the module manifest <code>.psd1</code> file.</li> </ul> <p>The <code>&lt;culture&gt;</code> subdirectory will be the current culture that PowerShell is executed under. To determine the current culture use <code>(Get-Culture).Name</code>. Alternatively, the culture can set by using the <code>-Culture</code> parameter of PSRule cmdlets.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#links","title":"Links","text":"<ul> <li>Get-PSRuleHelp</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/","title":"Expressions","text":"<p>Describes PSRule expressions and how to use them.</p>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#description","title":"Description","text":"<p>PSRule expressions are used within YAML-based rules or selectors to evaluate an object. Expressions are comprised of nested conditions, operators, and comparison properties.</p> <p>The following conditions are available:</p> <ul> <li>APIVersion</li> <li>Contains</li> <li>Count</li> <li>Equals</li> <li>EndsWith</li> <li>Exists</li> <li>Greater</li> <li>GreaterOrEquals</li> <li>HasDefault</li> <li>HasSchema</li> <li>HasValue</li> <li>In</li> <li>IsLower</li> <li>IsString</li> <li>IsArray</li> <li>IsBoolean</li> <li>IsDateTime</li> <li>IsInteger</li> <li>IsNumeric</li> <li>IsUpper</li> <li>Less</li> <li>LessOrEquals</li> <li>Like</li> <li>Match</li> <li>NotContains</li> <li>NotCount</li> <li>NotEndsWith</li> <li>NotEquals</li> <li>NotIn</li> <li>NotLike</li> <li>NotMatch</li> <li>NotStartsWith</li> <li>NotWithinPath</li> <li>SetOf</li> <li>StartsWith</li> <li>Subset</li> <li>WithinPath</li> <li>Version</li> </ul> <p>The following operators are available:</p> <ul> <li>AllOf</li> <li>AnyOf</li> <li>Not</li> </ul> <p>The following comparison properties are available:</p> <ul> <li>Field</li> <li>Name</li> <li>Scope</li> <li>Source</li> <li>Type</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#allof","title":"AllOf","text":"<p>The <code>allOf</code> operator is used to require all nested expressions to match. When any nested expression does not match, <code>allOf</code> does not match. This is similar to a logical and operation.</p> <p>Additionally sub-selectors can be used to modify the <code>allOf</code> operator. Sub-selectors allow filtering and looping through arrays of objects before the <code>allOf</code> operator is applied. See sub-selectors for more information.</p> <p>Syntax:</p> <pre><code>allOf: &lt;expression[]&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleAllOf'\nspec:\n  condition:\n    allOf:\n    # Both Name and Description must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'Description'\n      exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAllOf'\nspec:\n  if:\n    allOf:\n    # Both Name and Description must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'Description'\n      exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#anyof","title":"AnyOf","text":"<p>The <code>anyOf</code> operator is used to require one or more nested expressions to match. When any nested expression matches, <code>allOf</code> matches. This is similar to a logical or operation.</p> <p>Additionally sub-selectors can be used to modify the <code>anyOf</code> operator. Sub-selectors allow filtering and looping through arrays of objects before the <code>anyOf</code> operator is applied. See sub-selectors for more information.</p> <p>Syntax:</p> <pre><code>anyOf: &lt;expression[]&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleAnyOf'\nspec:\n  condition:\n    anyOf:\n    # Name and/ or AlternativeName must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'AlternativeName'\n      exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAnyOf'\nspec:\n  if:\n    anyOf:\n    # Name and/ or AlternativeName must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'AlternativeName'\n      exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#apiversion","title":"APIVersion","text":"<p>The <code>apiVersion</code> condition determines if the operand is a valid date version. A constraint can optionally be provided to require the date version to be within a range. Supported version constraints for expression are the same as the <code>$Assert.APIVersion</code> assertion helper.</p> <p>Syntax:</p> <pre><code>apiVersion: &lt;string&gt;\nincludePrerelease: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleAPIVersion'\nspec:\n  condition:\n    field: 'engine.apiVersion'\n    apiVersion: '&gt;=2015-10-01'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAnyAPIVersion'\nspec:\n  if:\n    field: 'engine.apiVersion'\n    apiVersion: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAPIVersionIncludingPrerelease'\nspec:\n  if:\n    field: 'engine.apiVersion'\n    apiVersion: '&gt;=2015-10-01'\n    includePrerelease: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#contains","title":"Contains","text":"<p>The <code>contains</code> condition can be used to determine if the operand contains a specified sub-string. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>contains: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, contains always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleContains'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      contains: '/azure/'\n    - field: 'url'\n      contains:\n      - 'github.io'\n      - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleContains'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      contains: '/azure/'\n    - field: 'url'\n      contains:\n      - 'github.io'\n      - 'github.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#count","title":"Count","text":"<p>The <code>count</code> condition is used to determine if the operand contains a specified number of items.</p> <p>Syntax:</p> <pre><code>count: &lt;int&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleCount'\nspec:\n  condition:\n    field: 'items'\n    count: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleCount'\nspec:\n  if:\n    field: 'items'\n    count: 2\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#equals","title":"Equals","text":"<p>The <code>equals</code> condition can be used to compare if the operand is equal to a supplied value.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   This only applies to string comparisons.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>equals: &lt;string | int | bool&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleEquals'\nspec:\n  condition:\n    field: 'Name'\n    equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleEquals'\nspec:\n  if:\n    field: 'Name'\n    equals: 'TargetObject1'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#endswith","title":"EndsWith","text":"<p>The <code>endsWith</code> condition can be used to determine if the operand ends with a specified string. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>endsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, endsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleEndsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'hostname'\n      endsWith: '.com'\n    - field: 'hostname'\n      endsWith:\n      - '.com.au'\n      - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleEndsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'hostname'\n      endsWith: '.com'\n    - field: 'hostname'\n      endsWith:\n      - '.com.au'\n      - '.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#exists","title":"Exists","text":"<p>The <code>exists</code> condition determines if the specified field exists.</p> <p>Syntax:</p> <pre><code>exists: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>exists: true</code>, exists will return <code>true</code> if the field exists.</li> <li>When <code>exists: false</code>, exists will return <code>true</code> if the field does not exist.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleExists'\nspec:\n  condition:\n    field: 'Name'\n    exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleExists'\nspec:\n  if:\n    field: 'Name'\n    exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#field","title":"Field","text":"<p>The comparison property <code>field</code> is used with a condition to determine field of the object to evaluate. A field can be:</p> <ul> <li>A property name.</li> <li>A key within a hashtable or dictionary.</li> <li>An index in an array or collection.</li> <li>A nested path through an object.</li> </ul> <p>Syntax:</p> <pre><code>field: &lt;string&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleField'\nspec:\n  condition:\n    field: 'Properties.securityRules[0].name'\n    exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleField'\nspec:\n  if:\n    field: 'Properties.securityRules[0].name'\n    exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greater","title":"Greater","text":"<p>The <code>greater</code> condition determines if the operand is greater than a supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>greater: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleGreater'\nspec:\n  condition:\n    field: 'Name'\n    greater: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleGreater'\nspec:\n  if:\n    field: 'Name'\n    greater: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greaterorequals","title":"GreaterOrEquals","text":"<p>The <code>greaterOrEquals</code> condition determines if the operand is greater or equal to the supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>greaterOrEquals: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleGreaterOrEquals'\nspec:\n  condition:\n    field: 'Name'\n    greaterOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleGreaterOrEquals'\nspec:\n  if:\n    field: 'Name'\n    greaterOrEquals: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasdefault","title":"HasDefault","text":"<p>The <code>hasDefault</code> condition determines if the field exists that it is set to the specified value. If the field does not exist, the condition will return <code>true</code>.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed for string values.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>hasDefault: &lt;string | int | bool&gt;\ncaseSensitive: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleHasDefault'\nspec:\n  condition:\n    field: 'enabled'\n    hasDefault: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasDefault'\nspec:\n  if:\n    field: 'enabled'\n    hasDefault: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasschema","title":"HasSchema","text":"<p>The <code>hasSchema</code> condition determines if the operand has a <code>$schema</code> property defined. If the <code>$schema</code> property is defined, it must match one of the specified schemas. If a trailing <code>#</code> is specified it is ignored.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>ignoreScheme</code> - Optionally, the URI scheme is ignored in the comparison.   By default, the scheme is compared.   When <code>true</code>, the schema will match if either <code>http://</code> or <code>https://</code> is specified.</li> </ul> <p>Syntax:</p> <pre><code>hasSchema: &lt;array&gt;\ncaseSensitive: &lt;bool&gt;\nignoreScheme: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>hasSchema: []</code>, hasSchema will return <code>true</code> if any non-empty <code>$schema</code> property is defined.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleHasSchema'\nspec:\n  condition:\n    field: '.'\n    hasSchema:\n    - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasSchema'\nspec:\n  if:\n    field: '.'\n    hasSchema:\n    - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n    - https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#\n    ignoreScheme: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasAnySchema'\nspec:\n  if:\n    field: '.'\n    hasSchema: []\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasvalue","title":"HasValue","text":"<p>The <code>hasValue</code> condition determines if the field exists and has a non-empty value.</p> <p>Syntax:</p> <pre><code>hasValue: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>hasValue: true</code>, hasValue will return <code>true</code> if the field is not empty.</li> <li>When <code>hasValue: false</code>, hasValue will return <code>true</code> if the field is empty.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleHasValue'\nspec:\n  condition:\n    field: 'Name'\n    hasValue: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasValue'\nspec:\n  if:\n    field: 'Name'\n    hasValue: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#in","title":"In","text":"<p>The <code>in</code> condition can be used to compare if a field contains one of the specified values.</p> <p>Syntax:</p> <pre><code>in: &lt;array&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIn'\nspec:\n  condition:\n    field: 'Name'\n    in:\n    - 'Value1'\n    - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIn'\nspec:\n  if:\n    field: 'Name'\n    in:\n    - 'Value1'\n    - 'Value2'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#islower","title":"IsLower","text":"<p>The <code>isLower</code> condition determines if the operand is a lowercase string.</p> <p>Syntax:</p> <pre><code>isLower: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isLower: true</code>, isLower will return <code>true</code> if the operand is a lowercase string.   Non-letter characters are ignored.</li> <li>When <code>isLower: false</code>, isLower will return <code>true</code> if the operand is not a lowercase string.</li> <li>If the operand is a field, and the field does not exist isLower always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIsLower'\nspec:\n  condition:\n    field: 'Name'\n    isLower: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIsLower'\nspec:\n  if:\n    field: 'Name'\n    isLower: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isstring","title":"IsString","text":"<p>The <code>isString</code> condition determines if the operand is a string or other type.</p> <p>Syntax:</p> <pre><code>isString: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isString: true</code>, isString will return <code>true</code> if the operand is a string.</li> <li>When <code>isString: false</code>, isString will return <code>true</code> if the operand is not a string or is null.</li> <li>If the operand is a field, and the field does not exist isString always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIsString'\nspec:\n  condition:\n    field: 'Name'\n    isString: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIsString'\nspec:\n  if:\n    field: 'Name'\n    isString: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isarray","title":"IsArray","text":"<p>The <code>isArray</code> condition determines if the operand is an array or other type.</p> <p>Syntax:</p> <pre><code>isArray: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isArray: true</code>, isArray will return <code>true</code> if the operand is an array.</li> <li>When <code>isArray: false</code>, isArray will return <code>true</code> if the operand is not an array or null.</li> <li>If the operand is a field, and the field does not exist, isArray always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isArray\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsArrayExample\nspec:\n  if:\n    field: 'Value'\n    isArray: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isboolean","title":"IsBoolean","text":"<p>The <code>isBoolean</code> condition determines if the operand is a boolean or other type.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to boolean type.   E.g. <code>'true'</code> can be converted to <code>true</code>.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isBoolean: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isBoolean: true</code>, isBoolean will return <code>true</code> if the operand is a boolean.</li> <li>When <code>isBoolean: false</code>, isBoolean will return <code>false</code> if the operand is not a boolean or null.</li> <li>When <code>convert: true</code>, types will be converted to boolean before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isBoolean\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsBooleanExample\nspec:\n  if:\n    field: 'Value'\n    isBoolean: true\n\n---\n# Synopsis: Using isBoolean with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsBooleanExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isBoolean: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isdatetime","title":"IsDateTime","text":"<p>The <code>isDateTime</code> condition determines if the operand is a datetime or other type.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to datetime type.   E.g. <code>'2021-04-03T15:00:00.00+10:00'</code> can be converted to a datetime.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isDateTime: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isDateTime: true</code>, isDateTime will return <code>true</code> if the operand is a datetime.</li> <li>When <code>isDateTime: false</code>, isDateTime will return <code>false</code> if the operand is not a datetime or null.</li> <li>When <code>convert: true</code>, types will be converted to datetime before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isDateTime\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsDateTimeExample\nspec:\n  if:\n    field: 'Value'\n    isDateTime: true\n\n---\n# Synopsis: Using isDateTime with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsDateTimeExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isDateTime: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isinteger","title":"IsInteger","text":"<p>The <code>isInteger</code> condition determines if the operand is a an integer or other type. The following types are considered integer types <code>int</code>, <code>long</code>, <code>byte</code>.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to integer type.   E.g. <code>'123'</code> can be converted to <code>123</code>.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isInteger: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isInteger: true</code>, isInteger will return <code>true</code> if the operand is an integer.</li> <li>When <code>isInteger: false</code>, isInteger will return <code>false</code> if the operand is not an integer or null.</li> <li>When <code>convert: true</code>, types will be converted to integer before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isInteger\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsIntegerExample\nspec:\n  if:\n    field: 'Value'\n    isInteger: true\n\n---\n# Synopsis: Using isInteger with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsIntegerExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isInteger: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isnumeric","title":"IsNumeric","text":"<p>The <code>isNumeric</code> condition determines if the operand is a a numeric or other type. The following types are considered numeric types <code>int</code>, <code>long</code>, <code>float</code>, <code>byte</code>, <code>double</code>.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to numeric type.   E.g. <code>'123'</code> can be converted to <code>123</code>.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isNumeric: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isNumeric: true</code>, isNumeric will return <code>true</code> if the operand is a numeric.</li> <li>When <code>isNumeric: false</code>, isNumeric will return <code>false</code> if the operand is not a numeric or null.</li> <li>When <code>convert: true</code>, types will be converted to numeric before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isNumeric\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsNumericExample\nspec:\n  if:\n    field: 'Value'\n    isNumeric: true\n\n---\n# Synopsis: Using isNumeric with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsNumercExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isNumeric: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isupper","title":"IsUpper","text":"<p>The <code>isUpper</code> condition determines if the operand is an uppercase string.</p> <p>Syntax:</p> <pre><code>isUpper: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isUpper: true</code>, isUpper will return <code>true</code> if the operand is an uppercase string.   Non-letter characters are ignored.</li> <li>When <code>isUpper: false</code>, isUpper will return <code>true</code> if the operand is not an uppercase string.</li> <li>If the operand is a field, and the field does not exist isUpper always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIsUpper'\nspec:\n  condition:\n    field: 'Name'\n    isUpper: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIsUpper'\nspec:\n  if:\n    field: 'Name'\n    isUpper: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#less","title":"Less","text":"<p>The <code>less</code> condition determines if the operand is less than a supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>less: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleLess'\nspec:\n  condition:\n    field: 'Name'\n    less: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleLess'\nspec:\n  if:\n    field: 'Name'\n    less: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#lessorequals","title":"LessOrEquals","text":"<p>The <code>lessOrEquals</code> condition determines if the operand is less or equal to the supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>lessOrEquals: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleLessOrEquals'\nspec:\n  condition:\n    field: 'Name'\n    lessOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleLessOrEquals'\nspec:\n  if:\n    field: 'Name'\n    lessOrEquals: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#like","title":"Like","text":"<p>The <code>like</code> condition can be used to determine if the operand matches a wildcard pattern. One or more patterns to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>like: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, like always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleLike'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      like: 'http://*'\n    - field: 'url'\n      like:\n      - 'http://*'\n      - 'https://*'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleLike'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      like: 'http://*'\n    - field: 'url'\n      like:\n      - 'http://*'\n      - 'https://*'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#match","title":"Match","text":"<p>The <code>match</code> condition can be used to compare if a field matches a supplied regular expression.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>match: &lt;string&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleMatch'\nspec:\n  condition:\n    field: 'Name'\n    match: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleMatch'\nspec:\n  if:\n    field: 'Name'\n    match: '$(abc|efg)$'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#name","title":"Name","text":"<p>The comparison property <code>name</code> is used with a condition to evaluate the target name of the object. The <code>name</code> property must be set to <code>.</code>. Any other value will cause the condition to evaluate to <code>false</code>.</p> <p>Syntax:</p> <pre><code>name: '.'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleName'\nspec:\n  condition:\n    name: '.'\n    equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleName'\nspec:\n  if:\n    name: '.'\n    in:\n    - 'TargetObject1'\n    - 'TargetObject2'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#not","title":"Not","text":"<p>The <code>any</code> operator is used to invert the result of the nested expression. When a nested expression matches, <code>not</code> does not match. When a nested expression does not match, <code>not</code> matches.</p> <p>Syntax:</p> <pre><code>not: &lt;expression&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNot'\nspec:\n  condition:\n    not:\n      # The AlternativeName field must not exist.\n      field: 'AlternativeName'\n      exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNot'\nspec:\n  if:\n    not:\n      # The AlternativeName field must not exist.\n      field: 'AlternativeName'\n      exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcontains","title":"NotContains","text":"<p>The <code>notContains</code> condition can be used to determine if the operand contains a specified sub-string. This condition fails when any of the specified sub-strings are found in the operand. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notContains: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notContains always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotContains'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      notContains: '/azure/'\n    - field: 'url'\n      notContains:\n      - 'github.io'\n      - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotContains'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      notContains: '/azure/'\n    - field: 'url'\n      notContains:\n      - 'github.io'\n      - 'github.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcount","title":"NotCount","text":"<p>The <code>notCount</code> condition is used to determine if the operand does not contain a specified number of items.</p> <p>Syntax:</p> <pre><code>notCount: &lt;int&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotCount'\nspec:\n  condition:\n    field: 'items'\n    notCount: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotCount'\nspec:\n  if:\n    field: 'items'\n    notCount: 2\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notendswith","title":"NotEndsWith","text":"<p>The <code>notEndsWith</code> condition can be used to determine if the operand ends with a specified string. This condition fails when any of the specified sub-strings are found at the end of the operand. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notEndsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notEndsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotEndsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'hostname'\n      notEndsWith: '.com'\n    - field: 'hostname'\n      notEndsWith:\n      - '.com.au'\n      - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotEndsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'hostname'\n      notEndsWith: '.com'\n    - field: 'hostname'\n      notEndsWith:\n      - '.com.au'\n      - '.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notequals","title":"NotEquals","text":"<p>The <code>notEquals</code> condition can be used to compare if a field is equal to a supplied value.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   This only applies to string comparisons.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notEquals: &lt;string | int | bool&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotEquals'\nspec:\n  condition:\n    field: 'Name'\n    notEquals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotEquals'\nspec:\n  if:\n    field: 'Name'\n    notEquals: 'TargetObject1'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notin","title":"NotIn","text":"<p>The <code>notIn</code> condition can be used to compare if a field does not contains one of the specified values.</p> <p>Syntax:</p> <pre><code>notIn: &lt;array&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotIn'\nspec:\n  condition:\n    field: 'Name'\n    notIn:\n    - 'Value1'\n    - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotIn'\nspec:\n  if:\n    field: 'Name'\n    notIn:\n    - 'Value1'\n    - 'Value2'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notlike","title":"NotLike","text":"<p>The <code>notLike</code> condition can be used to determine if the operand matches a wildcard pattern. This condition fails when any of the specified patterns match the operand. One or more patterns to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notLike: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notLike always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotLike'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      notLike: 'http://*'\n    - field: 'url'\n      notLike:\n      - 'http://'\n      - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotLike'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      notLike: 'http://*'\n    - field: 'url'\n      notLike:\n      - 'http://'\n      - 'https://'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notmatch","title":"NotMatch","text":"<p>The <code>notMatch</code> condition can be used to compare if a field does not matches a supplied regular expression.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>notMatch: &lt;string&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotMatch'\nspec:\n  condition:\n    field: 'Name'\n    notMatch: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotMatch'\nspec:\n  if:\n    field: 'Name'\n    notMatch: '$(abc|efg)$'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notstartswith","title":"NotStartsWith","text":"<p>The <code>notStartsWith</code> condition can be used to determine if the operand starts with a specified string. This condition fails when any of the specified sub-strings are found at the start of the operand. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notStartsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notStartsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotStartsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      notStartsWith: 'http'\n    - field: 'url'\n      notStartsWith:\n      - 'http://'\n      - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotStartsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      notStartsWith: 'http'\n    - field: 'url'\n      notStartsWith:\n      - 'http://'\n      - 'https://'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notwithinpath","title":"NotWithinPath","text":"<p>The <code>notWithinPath</code> condition determines if a file path is not within a required path.</p> <p>If the path is not within the required path, the condition will return <code>true</code>. If the path is within the required path, the condition will return <code>false</code>.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed for string values.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>notWithinPath: &lt;array&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\n# Synopsis: Test notWithinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceNotWithinPath\nspec:\n  if:\n    source: 'Template'\n    notWithinPath:\n      - \"deployments/path/\"\n\n---\n# Synopsis: Test notWithinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceNotWithinPathCaseSensitive\nspec:\n  if:\n    source: 'Template'\n    notWithinPath:\n      - \"Deployments/Path/\"\n    caseSensitive: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#scope","title":"Scope","text":"<p>The comparison property <code>scope</code> is used with a condition to evaluate any scopes assigned to the object. The <code>scope</code> property must be set to <code>.</code>. Any other value will cause the condition to evaluate to <code>false</code>.</p> <p>Syntax:</p> <pre><code>scope: '.'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleScope'\nspec:\n  condition:\n    scope: '.'\n    startsWith: '/'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleScope'\nspec:\n  if:\n    scope: '.'\n    startsWith: '/'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#setof","title":"SetOf","text":"<p>The <code>setOf</code> condition can be used to determine if the operand is a set of specified values. Additionally the following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>setOf: &lt;array&gt;\ncaseSensitive: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleSetOf'\nspec:\n  condition:\n    field: 'zones'\n    setOf:\n    - 1\n    - 2\n    - 3\n    caseSensitive: false\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleSetOf'\nspec:\n  if:\n    field: 'zones'\n    setOf:\n    - 1\n    - 2\n    - 3\n    caseSensitive: false\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#source","title":"Source","text":"<p>The comparison property <code>source</code> is used with a condition to expose the source path for the resource. The <code>source</code> property can be set to any value. The default is <code>file</code> when objects loaded from a file don't identify a source.</p> <p>Syntax:</p> <pre><code>source: 'file'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IgnoreTestFiles\nspec:\n  if:\n    source: 'file'\n    withinPath: 'tests/PSRule.Tests/'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#startswith","title":"StartsWith","text":"<p>The <code>startsWith</code> condition can be used to determine if the operand starts with a specified string. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>startsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, startsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleStartsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      startsWith: 'http'\n    - field: 'url'\n      startsWith:\n      - 'http://'\n      - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleStartsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      startsWith: 'http'\n    - field: 'url'\n      startsWith:\n      - 'http://'\n      - 'https://'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#subset","title":"Subset","text":"<p>The <code>subset</code> condition can be used to determine if the operand is a set of specified values. The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>unique</code> - Optionally, the operand must not contain duplicates.   By default, duplicates are allowed.</li> </ul> <p>Syntax:</p> <pre><code>subset: &lt;array&gt;\ncaseSensitive: &lt;bool&gt;\nunique: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleSubset'\nspec:\n  condition:\n    field: 'logs'\n    subset:\n    - 'cluster-autoscaler'\n    - 'kube-apiserver'\n    - 'kube-scheduler'\n    caseSensitive: true\n    unique: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleSubset'\nspec:\n  if:\n    field: 'logs'\n    subset:\n    - 'cluster-autoscaler'\n    - 'kube-apiserver'\n    - 'kube-scheduler'\n    caseSensitive: true\n    unique: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#type","title":"Type","text":"<p>The comparison property <code>type</code> is used with a condition to evaluate the target type of the object. The <code>type</code> property must be set to <code>.</code>. Any other value will cause the condition to evaluate to <code>false</code>.</p> <p>Syntax:</p> <pre><code>type: '.'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleType'\nspec:\n  condition:\n    type: '.'\n    equals: 'CustomType'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleType'\nspec:\n  if:\n    type: '.'\n    in:\n    - 'Microsoft.Storage/storageAccounts'\n    - 'Microsoft.Storage/storageAccounts/blobServices'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#version","title":"Version","text":"<p>The <code>version</code> condition determines if the operand is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range. Supported version constraints for expression are the same as the <code>$Assert.Version</code> assertion helper.</p> <p>Syntax:</p> <pre><code>version: &lt;string&gt;\nincludePrerelease: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleVersion'\nspec:\n  condition:\n    field: 'engine.version'\n    version: '^1.2.3'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAnyVersion'\nspec:\n  if:\n    field: 'engine.version'\n    version: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleVersionIncludingPrerelease'\nspec:\n  if:\n    field: 'engine.version'\n    version: '&gt;=1.5.0'\n    includePrerelease: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#withinpath","title":"WithinPath","text":"<p>The <code>withinPath</code> condition determines if a file path is within a required path.</p> <p>If the path is within the required path, the condition will return <code>true</code>. If the path is not within the required path, the condition will return <code>false</code>.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed for string values.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>withinPath: &lt;array&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\n# Synopsis: Test withinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceWithinPath\nspec:\n  if:\n    source: 'Template'\n    withinPath:\n      - \"deployments/path/\"\n\n---\n# Synopsis: Test withinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceWithinPathCaseSensitive\nspec:\n  if:\n    source: 'Template'\n    withinPath:\n      - \"Deployments/Path/\"\n    caseSensitive: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Options/","title":"Options","text":"<p>Describes additional options that can be used during rule execution.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#description","title":"Description","text":"<p>PSRule lets you use options when calling cmdlets such as <code>Invoke-PSRule</code> and <code>Test-PSRuleTarget</code> to change how rules are processed. This topic describes what options are available, when to and how to use them.</p> <p>The following workspace options are available for use:</p> <ul> <li>Baseline.Group</li> <li>Convention.Include</li> <li>Execution.AliasReference</li> <li>Execution.DuplicateResourceId</li> <li>Execution.HashAlgorithm</li> <li>Execution.LanguageMode</li> <li>Execution.InvariantCulture</li> <li>Execution.InitialSessionState</li> <li>Execution.RestrictScriptSource</li> <li>Execution.RuleInconclusive</li> <li>Execution.SuppressionGroupExpired</li> <li>Execution.UnprocessedObject</li> <li>Include.Module</li> <li>Include.Path</li> <li>Input.Format</li> <li>Input.IgnoreGitPath</li> <li>Input.IgnoreObjectSource</li> <li>Input.IgnoreRepositoryCommon</li> <li>Input.IgnoreUnchangedPath</li> <li>Input.ObjectPath</li> <li>Input.PathIgnore</li> <li>Input.TargetType</li> <li>Logging.LimitDebug</li> <li>Logging.LimitVerbose</li> <li>Logging.RuleFail</li> <li>Logging.RulePass</li> <li>Output.As</li> <li>Output.Banner</li> <li>Output.Culture</li> <li>Output.Encoding</li> <li>Output.Footer</li> <li>Output.Format</li> <li>Output.JobSummaryPath</li> <li>Output.JsonIndent</li> <li>Output.Outcome</li> <li>Output.Path</li> <li>Output.SarifProblemsOnly</li> <li>Output.Style</li> <li>Repository.BaseRef</li> <li>Repository.Url</li> <li>Requires</li> <li>Suppression</li> </ul> <p>Additionally the following baseline options can be included:</p> <ul> <li>Binding.Field</li> <li>Binding.IgnoreCase</li> <li>Binding.NameSeparator</li> <li>Binding.PreferTargetInfo</li> <li>Binding.TargetName</li> <li>Binding.TargetType</li> <li>Binding.UseQualifiedName</li> <li>Configuration</li> <li>Rule.Baseline</li> <li>Rule.Include</li> <li>Rule.IncludeLocal</li> <li>Rule.Exclude</li> <li>Rule.Tag</li> </ul> <p>See about_PSRule_Baseline for more information on baseline options.</p> <p>Options can be used with the following PSRule cmdlets:</p> <ul> <li>Export-PSRuleBaseline</li> <li>Get-PSRule</li> <li>Get-PSRuleBaseline</li> <li>Get-PSRuleHelp</li> <li>Invoke-PSRule</li> <li>Test-PSRuleTarget</li> </ul> <p>Each of these cmdlets support:</p> <ul> <li>Using the <code>-Option</code> parameter with an object created with the <code>New-PSRuleOption</code> cmdlet.   See cmdlet help for syntax and examples.</li> <li>Using the <code>-Option</code> parameter with a hashtable object.</li> <li>Using the <code>-Option</code> parameter with a YAML file path.</li> </ul> <p>When using a hashtable object <code>@{}</code>, one or more options can be specified as keys using a dotted notation.</p> <p>For example:</p> <pre><code>$option = @{ 'Output.Format' = 'Yaml' };\nInvoke-PSRule -Path . -Option $option;\n</code></pre> <pre><code>Invoke-PSRule -Path . -Option @{ 'Output.Format' = 'Yaml' };\n</code></pre> <p>The above example shows how the <code>Output.Format</code> option as a hashtable key can be used. Continue reading for a full list of options and how each can be used.</p> <p>Alternatively, options can be stored in a YAML formatted file and loaded from disk. Storing options as YAML allows different configurations to be loaded in a repeatable way instead of having to create an options object each time.</p> <p>Options are stored as YAML properties using a lower camel case naming convention, for example:</p> <pre><code>output:\n  format: Yaml\n</code></pre> <p>The <code>Set-PSRuleOption</code> cmdlet can be used to set options stored in YAML or the YAML file can be manually edited.</p> <pre><code>Set-PSRuleOption -OutputFormat Yaml;\n</code></pre> <p>By default, PSRule will automatically look for a default YAML options file in the current working directory. Alternatively, you can specify a specific file path.</p> <p>For example:</p> <pre><code>Invoke-PSRule -Option '.\\myconfig.yml';\n</code></pre> <pre><code>New-PSRuleOption -Path '.\\myconfig.yaml';\n</code></pre> <p>PSRule uses any of the following file names (in order) as the default YAML options file. If more than one of these files exist, the following order will be used to find the first match.</p> <ul> <li><code>ps-rule.yaml</code></li> <li><code>ps-rule.yml</code></li> <li><code>psrule.yaml</code></li> <li><code>psrule.yml</code></li> </ul> <p>We recommend only using lowercase characters as shown above. This is because not all operating systems treat case in the same way.</p> <p>Most options can be set using environment variables. When configuring environment variables we recommend that all capital letters are used. This is because environment variables are case-sensitive on some operating systems.</p> <p>PSRule environment variables use a consistent naming pattern of <code>PSRULE_&lt;PARENT&gt;_&lt;NAME&gt;</code>. Where <code>&lt;PARENT&gt;</code> is the parent class and <code>&lt;NAME&gt;</code> is the specific option. For example:</p> <ul> <li><code>Execution.InconclusiveWarning</code> is configured by <code>PSRULE_EXECUTION_INCONCLUSIVEWARNING</code>.</li> <li><code>Input.TargetType</code> is configured by <code>PSRULE_INPUT_TARGETTYPE</code>.</li> <li><code>Output.Format</code> is configured by <code>PSRULE_OUTPUT_FORMAT</code>.</li> </ul> <p>When setting environment variables:</p> <ul> <li>Enum values are set by string. For example <code>PSRULE_OUTPUT_FORMAT</code> could be set to <code>Yaml</code>. Enum values are case-insensitive.</li> <li>Boolean values are set by <code>true</code>, <code>false</code>, <code>1</code>, or <code>0</code>. For example <code>PSRULE_EXECUTION_INCONCLUSIVEWARNING</code> could be set to <code>false</code>. Boolean values are case-insensitive.</li> <li>String array values can specify multiple items by using a semi-colon separator. For example <code>PSRULE_INPUT_TARGETTYPE</code> could be set to <code>virtualMachine;virtualNetwork</code>.</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#baselinegroup","title":"Baseline.Group","text":"<p>You can use a baseline group to provide a friendly name to an existing baseline. When you run PSRule you can opt to use the baseline group name as an alternative name for the baseline. To indicate a baseline group, prefix the group name with <code>@</code> where you would use the name of a baseline.</p> <p>Baseline groups can be specified using:</p> <pre><code># PowerShell: Using the BaselineGroup parameter\n$option = New-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n</code></pre> <pre><code># PowerShell: Using the Baseline.Group hashtable key\n$option = New-PSRuleOption -Option @{ 'Baseline.Group' = @{ latest = 'YourBaseline' } };\n</code></pre> <pre><code># PowerShell: Using the BaselineGroup parameter to set YAML\nSet-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n</code></pre> <pre><code># YAML: Using the baseline/group property\nbaseline:\n  group:\n    latest: YourBaseline\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BASELINE_GROUP='latest=YourBaseline'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BASELINE_GROUP: 'latest=YourBaseline'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BASELINE_GROUP\n  value: 'latest=YourBaseline'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingfield","title":"Binding.Field","text":"<p>When an object is passed from the pipeline, PSRule automatically extracts fields from object properties. PSRule provides standard fields such as <code>TargetName</code> and <code>TargetType</code>. In addition to standard fields, custom fields can be bound. Custom fields are available to rules and included in output.</p> <p>PSRule uses the following logic to determine which property should be used for binding:</p> <ul> <li>By default PSRule will not extract any custom fields.</li> <li>If custom fields are configured, PSRule will attempt to bind the field.<ul> <li>If none of the configured property names exist, the field will be skipped.</li> <li>If more then one property name is configured, the order they are specified in the configuration determines precedence.<ul> <li>i.e. The first configured property name will take precedence over the second property name.</li> </ul> </li> <li>By default the property name will be matched ignoring case sensitivity.   To use a case sensitive match, configure the Binding.IgnoreCase option.</li> </ul> </li> </ul> <p>Custom field bindings can be specified using:</p> <pre><code># PowerShell: Using the BindingField parameter\n$option = New-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n</code></pre> <pre><code># PowerShell: Using the Binding.Field hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.Field' = @{ id = 'ResourceId', 'AlternativeId' } };\n</code></pre> <pre><code># PowerShell: Using the BindingField parameter to set YAML\nSet-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n</code></pre> <pre><code># YAML: Using the binding/field property\nbinding:\n  field:\n    id:\n    - ResourceId\n    - AlternativeId\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingignorecase","title":"Binding.IgnoreCase","text":"<p>When evaluating an object, PSRule extracts a few key properties from the object to help filter rules and display output results. The process of extract these key properties is called binding. The properties that PSRule uses for binding can be customized by providing a order list of alternative properties to use. See <code>Binding.TargetName</code> and <code>Binding.TargetType</code> for these options.</p> <ul> <li>By default, custom property binding finds the first matching property by name regardless of case. i.e. <code>Binding.IgnoreCase</code> is <code>true</code>.</li> <li>To make custom bindings case sensitive, set the <code>Binding.IgnoreCase</code> option to <code>false</code>.<ul> <li>Changing this option will affect custom property bindings for both TargetName and TargetType.</li> <li>Setting this option has no affect on binding defaults or custom scripts.</li> </ul> </li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingIgnoreCase parameter\n$option = New-PSRuleOption -BindingIgnoreCase $False;\n</code></pre> <pre><code># PowerShell: Using the Binding.IgnoreCase hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.IgnoreCase' = $False };\n</code></pre> <pre><code># PowerShell: Using the BindingIgnoreCase parameter to set YAML\nSet-PSRuleOption -BindingIgnoreCase $False;\n</code></pre> <pre><code># YAML: Using the binding/ignoreCase property\nbinding:\n  ignoreCase: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_IGNORECASE=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_IGNORECASE: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_IGNORECASE\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingnameseparator","title":"Binding.NameSeparator","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.</p> <p>In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName</p> <p>To use a qualified name, see the <code>Binding.UseQualifiedName</code> option.</p> <p>By default, PSRule uses <code>/</code> to separate TargetType from TargetName. This option configures the separator that PSRule uses between the two components.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingNameSeparator parameter\n$option = New-PSRuleOption -BindingNameSeparator '::';\n</code></pre> <pre><code># PowerShell: Using the Binding.NameSeparator hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.NameSeparator' = '::' };\n</code></pre> <pre><code># PowerShell: Using the BindingNameSeparator parameter to set YAML\nSet-PSRuleOption -BindingNameSeparator '::';\n</code></pre> <pre><code># YAML: Using the binding/nameSeparator property\nbinding:\n  nameSeparator: '::'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_NAMESEPARATOR='::'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_NAMESEPARATOR: '::'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_NAMESEPARATOR\n  value: '::'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingprefertargetinfo","title":"Binding.PreferTargetInfo","text":"<p>Some built-in objects within PSRule perform automatic binding of TargetName and TargetType. These built-in objects provide their own target info.</p> <p>When binding has been configured these values override automatic binding by default. This can occur when the built-in object uses one of the fields specified by the custom configuration. The common occurrences of this are on fields such as <code>Name</code> and <code>FullName</code> which are widely used. To prefer automatic binding when specified set this option to <code>$True</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingPreferTargetInfo parameter\n$option = New-PSRuleOption -BindingPreferTargetInfo $True;\n</code></pre> <pre><code># PowerShell: Using the Binding.PreferTargetInfo hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.PreferTargetInfo' = $True };\n</code></pre> <pre><code># PowerShell: Using the BindingPreferTargetInfo parameter to set YAML\nSet-PSRuleOption -BindingPreferTargetInfo $True;\n</code></pre> <pre><code># YAML: Using the binding/preferTargetInfo property\nbinding:\n  preferTargetInfo: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_PREFERTARGETINFO=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_PREFERTARGETINFO: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_PREFERTARGETINFO\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargetname","title":"Binding.TargetName","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another. Many objects could be passed down the pipeline at the same time, so using a TargetName that is meaningful is important. TargetName is also used for advanced features such as rule suppression.</p> <p>The value that PSRule uses for TargetName is configurable. PSRule uses the following logic to determine what TargetName should be used:</p> <ul> <li>By default PSRule will:<ul> <li>Use <code>TargetName</code> or <code>Name</code> properties on the object. These property names are case insensitive.</li> <li>If both <code>TargetName</code> and <code>Name</code> properties exist, <code>TargetName</code> will take precedence over <code>Name</code>.</li> <li>If neither <code>TargetName</code> or <code>Name</code> properties exist, a hash of the object will be used as TargetName.</li> <li>The hash algorithm used can be set by the <code>Execution.HashAlgorithm</code> option.</li> </ul> </li> <li>If custom TargetName binding properties are configured, the property names specified will override the defaults.<ul> <li>If none of the configured property names exist, PSRule will revert back to <code>TargetName</code> then <code>Name</code>.</li> <li>If more then one property name is configured, the order they are specified in the configuration determines precedence.<ul> <li>i.e. The first configured property name will take precedence over the second property name.</li> </ul> </li> <li>By default the property name will be matched ignoring case sensitivity.   To use a case sensitive match, configure the Binding.IgnoreCase option.</li> </ul> </li> <li>If a custom TargetName binding function is specified, the function will be evaluated first before any other option.<ul> <li>If the function returns <code>$Null</code> then custom properties, <code>TargetName</code> and <code>Name</code> properties will be used.</li> <li>The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.</li> <li>Custom binding functions are blocked in constrained language mode is used.   See language mode for more information.</li> </ul> </li> </ul> <p>Custom property names to use for binding can be specified using:</p> <pre><code># PowerShell: Using the TargetName parameter\n$option = New-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n</code></pre> <pre><code># PowerShell: Using the Binding.TargetName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetName' = 'ResourceName', 'AlternateName' };\n</code></pre> <pre><code># PowerShell: Using the TargetName parameter to set YAML\nSet-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n</code></pre> <pre><code># YAML: Using the binding/targetName property\nbinding:\n  targetName:\n  - ResourceName\n  - AlternateName\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_TARGETNAME='ResourceName;AlternateName'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_TARGETNAME: 'ResourceName;AlternateName'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETNAME\n  value: 'ResourceName;AlternateName'\n</code></pre> <p>To specify a custom binding function use:</p> <pre><code># Create a custom function that returns a TargetName string\n$bindFn = {\n    param ($TargetObject)\n\n    $otherName = $TargetObject.PSObject.Properties['OtherName'];\n    if ($Null -eq $otherName) { return $Null }\n    return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargettype","title":"Binding.TargetType","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetType. TargetType is used to filter rules based on object type and appears in output results.</p> <p>The value that PSRule uses for TargetType is configurable. PSRule uses the following logic to determine what TargetType should be used:</p> <ul> <li>By default PSRule will:<ul> <li>Use the default type presented by PowerShell from <code>TypeNames</code>. i.e. <code>.PSObject.TypeNames[0]</code></li> </ul> </li> <li>If custom TargetType binding properties are configured, the property names specified will override the defaults.<ul> <li>If none of the configured property names exist, PSRule will revert back to the type presented by PowerShell.</li> <li>If more then one property name is configured, the order they are specified in the configuration determines precedence.<ul> <li>i.e. The first configured property name will take precedence over the second property name.</li> </ul> </li> <li>By default the property name will be matched ignoring case sensitivity.   To use a case sensitive match, configure the <code>Binding.IgnoreCase</code> option.</li> </ul> </li> <li>If a custom TargetType binding function is specified, the function will be evaluated first before any other option.<ul> <li>If the function returns <code>$Null</code> then custom properties, or the type presented by PowerShell will be used in order instead.</li> <li>The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.</li> <li>Custom binding functions are blocked in constrained language mode is used.   See language mode for more information.</li> </ul> </li> </ul> <p>Custom property names to use for binding can be specified using:</p> <pre><code># PowerShell: Using the TargetType parameter\n$option = New-PSRuleOption -TargetType 'ResourceType', 'kind';\n</code></pre> <pre><code># PowerShell: Using the Binding.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetType' = 'ResourceType', 'kind' };\n</code></pre> <pre><code># PowerShell: Using the TargetType parameter to set YAML\nSet-PSRuleOption -TargetType 'ResourceType', 'kind';\n</code></pre> <pre><code># YAML: Using the binding/targetType property\nbinding:\n  targetType:\n  - ResourceType\n  - kind\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_TARGETTYPE='ResourceType;kind'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_TARGETTYPE: 'ResourceType;kind'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETTYPE\n  value: 'ResourceType;kind'\n</code></pre> <p>To specify a custom binding function use:</p> <pre><code># Create a custom function that returns a TargetType string\n$bindFn = {\n    param ($TargetObject)\n\n    $otherType = $TargetObject.PSObject.Properties['OtherType'];\n\n    if ($otherType -eq $Null) {\n        return $Null\n    }\n\n    return $otherType.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetType $bindFn;\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingusequalifiedname","title":"Binding.UseQualifiedName","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.</p> <p>In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName</p> <p>This option determines if PSRule uses qualified or unqualified names (default).</p> <p>By default, PSRule uses <code>/</code> to separate TargetType from TargetName. Set <code>Binding.NameSeparator</code> to change.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingUseQualifiedName parameter\n$option = New-PSRuleOption -BindingUseQualifiedName $True;\n</code></pre> <pre><code># PowerShell: Using the Binding.UseQualifiedName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.UseQualifiedName' = $True };\n</code></pre> <pre><code># PowerShell: Using the BindingUseQualifiedName parameter to set YAML\nSet-PSRuleOption -BindingUseQualifiedName $True;\n</code></pre> <pre><code># YAML: Using the binding/useQualifiedName property\nbinding:\n  useQualifiedName: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_USEQUALIFIEDNAME=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_USEQUALIFIEDNAME: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_USEQUALIFIEDNAME\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#configuration","title":"Configuration","text":"<p>Configures a set of baseline configuration values that can be used in rule definitions. Configuration values can be overridden at different scopes.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Configuration option with a hashtable\n$option = New-PSRuleOption -Configuration @{ LOCAL_APPSERVICEMININSTANCECOUNT = 2 };\n</code></pre> <pre><code># YAML: Using the configuration property\nconfiguration:\n  LOCAL_APPSERVICEMININSTANCECOUNT: 2\n</code></pre> <p>Configuration values can be specified using environment variables. To specify a configuration value, prefix the configuration value with <code>PSRULE_CONFIGURATION_</code>.</p> <pre><code># Bash: Using environment variable\nexport PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT=2\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT: '2'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT\n  value: '2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#conventioninclude","title":"Convention.Include","text":"<p>Specifies conventions to execute when the pipeline run. Conventions are included by name and must be defined within files included in <code>-Path</code> or <code>-Module</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Convention parameter\n$option = New-PSRuleOption -Convention 'Convention1', 'Convention2';\n</code></pre> <pre><code># PowerShell: Using the Convention.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Convention.Include' = $True };\n</code></pre> <pre><code># PowerShell: Using the Convention parameter to set YAML\nSet-PSRuleOption -Convention 'Convention1', 'Convention2';\n</code></pre> <pre><code># YAML: Using the convention/include property\nconvention:\n  include:\n  - 'Convention1'\n  - 'Convention2'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_CONVENTION_INCLUDE='Convention1;Convention2'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_CONVENTION_INCLUDE: 'Convention1;Convention2'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONVENTION_INCLUDE\n  value: 'Convention1;Convention2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionaliasreference","title":"Execution.AliasReference","text":"<p> v2.9.0</p> <p>Determines how to handle when an alias to a resource is used. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionAliasReference parameter\n$option = New-PSRuleOption -ExecutionAliasReference 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.AliasReference hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.AliasReference' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionAliasReference parameter to set YAML\nSet-PSRuleOption -ExecutionAliasReference 'Error';\n</code></pre> <pre><code># YAML: Using the execution/aliasReference property\nexecution:\n  aliasReference: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_ALIASREFERENCE=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_ALIASREFERENCE: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_ALIASREFERENCE\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionduplicateresourceid","title":"Execution.DuplicateResourceId","text":"<p> v2.4.0</p> <p>Determines how to handle duplicate resources identifiers during execution. A duplicate resource identifier may exist if two resources are defined with the same name, ref, or alias. By default, an error is thrown, however this behavior can be modified by this option.</p> <p>If this option is configured to <code>Warn</code> or <code>Ignore</code> only the first resource will be used, however PSRule will continue to execute.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Error</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.</li> <li><code>Error</code> (3) - Abort and throw an error.   This is the default.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the DuplicateResourceId parameter\n$option = New-PSRuleOption -DuplicateResourceId 'Warn';\n</code></pre> <pre><code># PowerShell: Using the Execution.DuplicateResourceId hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.DuplicateResourceId' = 'Warn' };\n</code></pre> <pre><code># PowerShell: Using the DuplicateResourceId parameter to set YAML\nSet-PSRuleOption -DuplicateResourceId 'Warn';\n</code></pre> <pre><code># YAML: Using the execution/duplicateResourceId property\nexecution:\n  duplicateResourceId: Warn\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_DUPLICATERESOURCEID=Warn\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_DUPLICATERESOURCEID: Warn\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_DUPLICATERESOURCEID\n  value: Warn\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionhashalgorithm","title":"Execution.HashAlgorithm","text":"<p> v3.0.0</p> <p>Specifies the hashing algorithm used by the PSRule runtime. This hash algorithm is used when generating a resource identifier for an object that does not have a bound name.</p> <p>By default, the SHA512 algorithm is used.</p> <p>The following algorithms are available for use in PSRule:</p> <ul> <li><code>SHA512</code></li> <li><code>SHA384</code></li> <li><code>SHA256</code></li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Execution.HashAlgorithm hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.HashAlgorithm' = 'SHA256' };\n</code></pre> <pre><code># YAML: Using the execution/hashAlgorithm property\nexecution:\n  hashAlgorithm: SHA256\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_HASHALGORITHM=SHA256\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_HASHALGORITHM: SHA256\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_HASHALGORITHM\n  value: SHA256\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionlanguagemode","title":"Execution.LanguageMode","text":"<p>Unless PowerShell has been constrained, full language features of PowerShell are available to use within rule definitions. In locked down environments, a reduced set of language features may be desired.</p> <p>When PSRule is executed in an environment configured for Device Guard, only constrained language features are available.</p> <p>The following language modes are available for use in PSRule:</p> <ul> <li><code>FullLanguage</code> - Executes with all language features.   This is the default.</li> <li><code>ConstrainedLanguage</code> - Executes in constrained language mode that restricts the types and methods that can be used.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Execution.LanguageMode hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.LanguageMode' = 'ConstrainedLanguage' };\n</code></pre> <pre><code># YAML: Using the execution/languageMode property\nexecution:\n  languageMode: ConstrainedLanguage\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_LANGUAGEMODE=ConstrainedLanguage\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_LANGUAGEMODE: ConstrainedLanguage\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_LANGUAGEMODE\n  value: ConstrainedLanguage\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninvariantculture","title":"Execution.InvariantCulture","text":"<p> v2.9.0</p> <p>Determines how to report when an invariant culture is used. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionInvariantCulture parameter\n$option = New-PSRuleOption -ExecutionInvariantCulture 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.InvariantCulture hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InvariantCulture' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionInvariantCulture parameter to set YAML\nSet-PSRuleOption -ExecutionInvariantCulture 'Error';\n</code></pre> <pre><code># YAML: Using the execution/invariantCulture property\nexecution:\n  invariantCulture: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_INVARIANTCULTURE=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_INVARIANTCULTURE: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INVARIANTCULTURE\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninitialsessionstate","title":"Execution.InitialSessionState","text":"<p> v2.5.0</p> <p>Determines how the initial session state for executing PowerShell code is created.</p> <p>The following preferences are available:</p> <ul> <li><code>BuiltIn</code> (0) - Create the initial session state with all built-in cmdlets loaded.   This is the default.</li> <li><code>Minimal</code> (1) - Create the initial session state with only a minimum set of cmdlets loaded.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InitialSessionState parameter\n$option = New-PSRuleOption -InitialSessionState 'Minimal';\n</code></pre> <pre><code># PowerShell: Using the Execution.InitialSessionState hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InitialSessionState' = 'Minimal' };\n</code></pre> <pre><code># PowerShell: Using the InitialSessionState parameter to set YAML\nSet-PSRuleOption -InitialSessionState 'Minimal';\n</code></pre> <pre><code># YAML: Using the execution/initialSessionState property\nexecution:\n  initialSessionState: Minimal\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_INITIALSESSIONSTATE=Minimal\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_INITIALSESSIONSTATE: Minimal\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INITIALSESSIONSTATE\n  value: Minimal\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrestrictscriptsource","title":"Execution.RestrictScriptSource","text":"<p> v3.0.0</p> <p>Configures where to allow PowerShell language features (such as rules and conventions) to run from. In locked down environments, running PowerShell scripts from the workspace may not be allowed. Only run scripts from a trusted source.</p> <p>This option does not affect YAML or JSON based rules and resources.</p> <p>The following script source restrictions are available:</p> <ul> <li><code>Unrestricted</code> - PowerShell language features are allowed from workspace and modules.   This is the default.</li> <li><code>ModuleOnly</code> - PowerShell language features are allowed from loaded modules,   but script files within the workspace are ignored.</li> <li><code>DisablePowerShell</code> - No PowerShell language features are used during PSRule run.   When this mode is used, rules and conventions written in PowerShell will not execute.   Modules that use PowerShell rules and conventions may not work as expected.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RestrictScriptSource parameter\n$option = New-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n</code></pre> <pre><code># PowerShell: Using the Execution.RestrictScriptSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RestrictScriptSource' = 'ModuleOnly' };\n</code></pre> <pre><code># PowerShell: Using the RestrictScriptSource parameter to set YAML\nSet-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n</code></pre> <pre><code># YAML: Using the execution/restrictScriptSource property\nexecution:\n  restrictScriptSource: ModuleOnly\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE=ModuleOnly\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE: ModuleOnly\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE\n  value: ModuleOnly\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleinconclusive","title":"Execution.RuleInconclusive","text":"<p> v2.9.0</p> <p>Determines how to handle rules that generate inconclusive results. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionRuleInconclusive parameter\n$option = New-PSRuleOption -ExecutionRuleInconclusive 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.RuleInconclusive hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleInconclusive' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionRuleInconclusive parameter to set YAML\nSet-PSRuleOption -ExecutionRuleInconclusive 'Error';\n</code></pre> <pre><code># YAML: Using the execution/ruleInconclusive property\nexecution:\n  ruleInconclusive: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEINCONCLUSIVE=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RULEINCONCLUSIVE: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEINCONCLUSIVE\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionsuppressiongroupexpired","title":"Execution.SuppressionGroupExpired","text":"<p> v2.6.0</p> <p>Determines how to handle expired suppression groups. Regardless of the value, an expired suppression group will be ignored. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the SuppressionGroupExpired parameter\n$option = New-PSRuleOption -SuppressionGroupExpired 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.SuppressionGroupExpired hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.SuppressionGroupExpired' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the SuppressionGroupExpired parameter to set YAML\nSet-PSRuleOption -SuppressionGroupExpired 'Error';\n</code></pre> <pre><code># YAML: Using the execution/suppressionGroupExpired property\nexecution:\n  suppressionGroupExpired: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleexcluded","title":"Execution.RuleExcluded","text":"<p> v2.8.0</p> <p>Determines how to handle excluded rules. Regardless of the value, excluded rules are ignored. By default, a rule is excluded silently, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Ignore</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.   This is the default.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionRuleExcluded parameter\n$option = New-PSRuleOption -ExecutionRuleExcluded 'Warn';\n</code></pre> <pre><code># PowerShell: Using the Execution.RuleExcluded hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleExcluded' = 'Warn' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionRuleExcluded parameter to set YAML\nSet-PSRuleOption -ExecutionRuleExcluded 'Warn';\n</code></pre> <pre><code># YAML: Using the execution/ruleExcluded property\nexecution:\n  ruleExcluded: Warn\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEEXCLUDED=Warn\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RULEEXCLUDED: Warn\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEEXCLUDED\n  value: Warn\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrulesuppressed","title":"Execution.RuleSuppressed","text":"<p> v2.8.0</p> <p>Determines how to handle suppressed rules. Regardless of the value, a suppressed rule is ignored. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <pre><code># PowerShell: Using the ExecutionRuleSuppressed parameter\n$option = New-PSRuleOption -ExecutionRuleSuppressed 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.RuleSuppressed hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleSuppressed' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionRuleSuppressed parameter to set YAML\nSet-PSRuleOption -ExecutionRuleSuppressed 'Error';\n</code></pre> <pre><code># YAML: Using the execution/ruleSuppressed property\nexecution:\n  ruleSuppressed: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RULESUPPRESSED=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RULESUPPRESSED: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULESUPPRESSED\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionunprocessedobject","title":"Execution.UnprocessedObject","text":"<p> v2.9.0</p> <p>Determines how to report objects that are not processed by any rule. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionUnprocessedObject parameter\n$option = New-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n</code></pre> <pre><code># PowerShell: Using the Execution.UnprocessedObject hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.UnprocessedObject' = 'Ignore' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionUnprocessedObject parameter to set YAML\nSet-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n</code></pre> <pre><code># YAML: Using the execution/unprocessedObject property\nexecution:\n  unprocessedObject: Ignore\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_UNPROCESSEDOBJECT: Ignore\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_UNPROCESSEDOBJECT\n  value: Ignore\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includemodule","title":"Include.Module","text":"<p>Automatically include rules and resources from the specified module. To automatically import and include a module specify the module by name. The module must already be installed on the system.</p> <p>When <code>$PSModuleAutoLoadingPreference</code> is set to a value other then <code>All</code> the module must be imported.</p> <p>This option is equivalent to using the <code>-Module</code> parameter on PSRule cmdlets, with the following addition:</p> <ul> <li>Modules specified with <code>Include.Module</code> are combined with <code>-Module</code>.   Both sets of modules will be imported and used using execution.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the IncludeModule parameter\n$option = New-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n</code></pre> <pre><code># PowerShell: Using the Include.Module hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Module' = 'TestModule1', 'TestModule2' };\n</code></pre> <pre><code># PowerShell: Using the IncludeModule parameter to set YAML\nSet-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n</code></pre> <pre><code># YAML: Using the include/module property\ninclude:\n  module:\n  - TestModule1\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INCLUDE_MODULE=TestModule1;TestModule2\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INCLUDE_MODULE: TestModule1;TestModule2\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_MODULE\n  value: TestModule1;TestModule2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includepath","title":"Include.Path","text":"<p>Automatically include rules and resources from the specified path. By default, <code>.ps-rule/</code> is included.</p> <p>This option is equivalent to using the <code>-Path</code> parameter on PSRule cmdlets, with the following additions:</p> <ul> <li>Paths specified with <code>Include.Path</code> are combined with <code>-Path</code>.   Both sets of paths will be imported and used using execution.</li> <li>The <code>Include.Path</code> option defaults to <code>.ps-rule/</code>.   To override this default, specify one or more alternative paths or an empty array.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the IncludePath parameter\n$option = New-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n</code></pre> <pre><code># PowerShell: Using the Include.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Path' = '.ps-rule/', 'custom-rules/' };\n</code></pre> <pre><code># PowerShell: Using the IncludePath parameter to set YAML\nSet-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n</code></pre> <pre><code># YAML: Using the include/path property\ninclude:\n  path:\n  - custom-rules/\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INCLUDE_PATH=.ps-rule/;custom-rules/\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INCLUDE_PATH: .ps-rule/;custom-rules/\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_PATH\n  value: .ps-rule/;custom-rules/\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputformat","title":"Input.Format","text":"<p>Configures the input format for when a string is passed in as a target object. This option determines if the target object is deserialized into an alternative form.</p> <p>Use this option with <code>Assert-PSRule</code>, <code>Invoke-PSRule</code> or <code>Test-PSRuleTarget</code>. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to deserialize as a specific format. The <code>-Format</code> parameter will override any value set in configuration.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. <code>FileInfo</code> objects for supported file formats will be deserialized based on file extension.</p> <p>When the <code>-InputPath</code> parameter is used, supported file formats will be deserialized based on file extension. The <code>-InputPath</code> parameter can be used with a file path or URL.</p> <p>The following formats are available:</p> <ul> <li>None - Treat strings as plain text and do not deserialize files.</li> <li>Yaml - Deserialize as one or more YAML objects.</li> <li>Json - Deserialize as one or more JSON objects.</li> <li>Markdown - Deserialize as a markdown object.</li> <li>PowerShellData - Deserialize as a PowerShell data object.</li> <li>File - Files are not deserialized.</li> <li>Detect - Detect format based on file extension. This is the default.</li> </ul> <p>If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When the file extension can not be determined <code>Detect</code> is the same as <code>None</code>.</p> <p>The <code>Markdown</code> format does not parse the whole markdown document. Specifically this format deserializes YAML front matter from the top of the document if any exists.</p> <p>The <code>File</code> format does not deserialize file contents. Each file is returned as an object. Files within <code>.git</code> sub-directories are ignored. Path specs specified in <code>.gitignore</code> directly in the current working path are ignored. A <code>RepositoryInfo</code> object is generated if the current working path if a <code>.git</code> sub-directory is present. Additionally, PSRule performs automatic type binding for file objects, using the extension as the type. When files have no extension the whole file name is used.</p> <p>Detect uses the following file extensions:</p> <ul> <li>Yaml - <code>.yaml</code> or <code>.yml</code></li> <li>Json - <code>.json</code> or <code>.jsonc</code></li> <li>Markdown - <code>.md</code> or <code>.markdown</code></li> <li>PowerShellData - <code>.psd1</code></li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Format parameter\n$option = New-PSRuleOption -Format Yaml;\n</code></pre> <pre><code># PowerShell: Using the Input.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.Format' = 'Yaml' };\n</code></pre> <pre><code># PowerShell: Using the Format parameter to set YAML\nSet-PSRuleOption -Format Yaml;\n</code></pre> <pre><code># YAML: Using the input/format property\ninput:\n  format: Yaml\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_FORMAT=Yaml\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_FORMAT: Yaml\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_FORMAT\n  value: Yaml\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoregitpath","title":"Input.IgnoreGitPath","text":"<p>When reading files from an input path, files within the <code>.git</code> sub-directory are ignored by default. Files stored within the <code>.git</code> sub-directory are system repository files used by git. To read files stored within the <code>.git</code> path, set this option to <code>$False</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreGitPath parameter\n$option = New-PSRuleOption -InputIgnoreGitPath $False;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreGitPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreGitPath' = $False };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreGitPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreGitPath $False;\n</code></pre> <pre><code># YAML: Using the input/ignoreGitPath property\ninput:\n  ignoreGitPath: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREGITPATH=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREGITPATH: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREGITPATH\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreobjectsource","title":"Input.IgnoreObjectSource","text":"<p>By default, objects read from file using <code>inputPath</code> will be skipped if the file path has been ignored. When set to true, additionally objects with a source path that has been ignored will be skipped. This will include <code>FileInfo</code> objects, and objects with a source set using the <code>_PSRule.source</code> property.</p> <p>File paths to ignore are set by <code>Input.PathIgnore</code>, <code>Input.IgnoreGitPath</code>, and <code>Input.IgnoreRepositoryCommon</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreObjectSource parameter\n$option = New-PSRuleOption -InputIgnoreObjectSource $True;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreObjectSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreObjectSource' = $True };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreObjectSource parameter to set YAML\nSet-PSRuleOption -InputIgnoreObjectSource $True;\n</code></pre> <pre><code># YAML: Using the input/ignoreObjectSource property\ninput:\n  ignoreObjectSource: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREOBJECTSOURCE=true\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREOBJECTSOURCE: true\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREOBJECTSOURCE\n  value: true\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignorerepositorycommon","title":"Input.IgnoreRepositoryCommon","text":"<p>When reading files from an input path, files are discovered recursively. A number of files are commonly found within a private and open-source repositories. In many cases these files are of no interest for analysis and should be ignored by rules. PSRule will ignore the following files by default:</p> <ul> <li><code>README.md</code></li> <li><code>.DS_Store</code></li> <li><code>.gitignore</code></li> <li><code>.gitattributes</code></li> <li><code>.gitmodules</code></li> <li><code>LICENSE</code></li> <li><code>LICENSE.txt</code></li> <li><code>CODE_OF_CONDUCT.md</code></li> <li><code>CONTRIBUTING.md</code></li> <li><code>SECURITY.md</code></li> <li><code>SUPPORT.md</code></li> <li><code>.vscode/*.json</code></li> <li><code>.vscode/*.code-snippets</code></li> <li><code>.github/**/*.md</code></li> <li><code>.github/CODEOWNERS</code></li> <li><code>.pipelines/**/*.yml</code></li> <li><code>.pipelines/**/*.yaml</code></li> <li><code>.azure-pipelines/**/*.yml</code></li> <li><code>.azure-pipelines/**/*.yaml</code></li> <li><code>.azuredevops/*.md</code></li> </ul> <p>To include these files, set this option to <code>$False</code>. This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreRepositoryCommon parameter\n$option = New-PSRuleOption -InputIgnoreRepositoryCommon $False;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreRepositoryCommon hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreRepositoryCommon' = $False };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreRepositoryCommon parameter to set YAML\nSet-PSRuleOption -InputIgnoreRepositoryCommon $False;\n</code></pre> <pre><code># YAML: Using the input/ignoreRepositoryCommon property\ninput:\n  ignoreRepositoryCommon: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREREPOSITORYCOMMON=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREREPOSITORYCOMMON: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREREPOSITORYCOMMON\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreunchangedpath","title":"Input.IgnoreUnchangedPath","text":"<p> v2.5.0</p> <p>By default, PSRule will process all files within an input path. For large repositories, this can result in a large number of files being processed. Additionally, for a pull request you may only be interested in files that have changed.</p> <p>When set to <code>true</code>, files that have not changed will be ignored. This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreUnchangedPath parameter\n$option = New-PSRuleOption -InputIgnoreUnchangedPath $True;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreUnchangedPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreUnchangedPath' = $True };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreUnchangedPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreUnchangedPath $True;\n</code></pre> <pre><code># YAML: Using the input/ignoreUnchangedPath property\ninput:\n  ignoreUnchangedPath: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREUNCHANGEDPATH=true\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREUNCHANGEDPATH\n  value: true\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputobjectpath","title":"Input.ObjectPath","text":"<p>The object path to a property to use instead of the pipeline object.</p> <p>By default, PSRule processes objects passed from the pipeline against selected rules. When this option is set, instead of evaluating the pipeline object, PSRule looks for a property of the pipeline object specified by <code>ObjectPath</code> and uses that instead. If the property specified by <code>ObjectPath</code> is a collection/ array, then each item is evaluated separately.</p> <p>If the property specified by <code>ObjectPath</code> does not exist, PSRule skips the object.</p> <p>When using <code>Invoke-PSRule</code>, <code>Test-PSRuleTarget</code>, and <code>Assert-PSRule</code> the <code>-ObjectPath</code> parameter will override any value set in configuration.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ObjectPath parameter\n$option = New-PSRuleOption -ObjectPath 'items';\n</code></pre> <pre><code># PowerShell: Using the Input.ObjectPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.ObjectPath' = 'items' };\n</code></pre> <pre><code># PowerShell: Using the ObjectPath parameter to set YAML\nSet-PSRuleOption -ObjectPath 'items';\n</code></pre> <pre><code># YAML: Using the input/objectPath property\ninput:\n  objectPath: items\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_OBJECTPATH=items\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_OBJECTPATH: items\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_OBJECTPATH\n  value: items\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputpathignore","title":"Input.PathIgnore","text":"<p>Ignores input files that match the path spec when using <code>-InputPath</code>. If specified, files that match the path spec will not be processed. By default, all files are processed.</p> <p>For example, ignoring file extensions:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude files with these extensions\n  - '*.md'\n  - '*.png'\n  # Exclude specific configuration files\n  - 'bicepconfig.json'\n</code></pre> <p>For example, ignoring all files with exceptions:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude all files\n  - '*'\n  # Only process deploy.bicep files\n  - '!**/deploy.bicep'\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputPathIgnore parameter\n$option = New-PSRuleOption -InputPathIgnore '*.Designer.cs';\n</code></pre> <pre><code># PowerShell: Using the Input.PathIgnore hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.PathIgnore' = '*.Designer.cs' };\n</code></pre> <pre><code># PowerShell: Using the InputPathIgnore parameter to set YAML\nSet-PSRuleOption -InputPathIgnore '*.Designer.cs';\n</code></pre> <pre><code># YAML: Using the input/pathIgnore property\ninput:\n  pathIgnore:\n  - '*.Designer.cs'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_PATHIGNORE=*.Designer.cs\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_PATHIGNORE: '*.Designer.cs'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_PATHIGNORE\n  value: '*.Designer.cs'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputtargettype","title":"Input.TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This option is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option.</p> <p>When using <code>Invoke-PSRule</code>, <code>Test-PSRuleTarget</code>, and <code>Assert-PSRule</code> the <code>-TargetType</code> parameter will override any value set in configuration.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputTargetType parameter\n$option = New-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n</code></pre> <pre><code># PowerShell: Using the Input.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.TargetType' = 'virtualMachine', 'virtualNetwork' };\n</code></pre> <pre><code># PowerShell: Using the InputTargetType parameter to set YAML\nSet-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n</code></pre> <pre><code># YAML: Using the input/targetType property\ninput:\n  targetType:\n  - virtualMachine\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_TARGETTYPE=virtualMachine;virtualNetwork\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_TARGETTYPE: virtualMachine;virtualNetwork\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_TARGETTYPE\n  value: virtualMachine;virtualNetwork\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitdebug","title":"Logging.LimitDebug","text":"<p>Limits debug messages to a list of named debug scopes.</p> <p>When using the <code>-Debug</code> switch or preference variable, by default PSRule cmdlets log all debug output. When using debug output for debugging a specific rule, it may be helpful to limit debug message to a specific rule.</p> <p>To identify a rule to include in debug output use the rule name.</p> <p>The following built-in scopes exist in addition to rule names:</p> <ul> <li><code>[Discovery.Source]</code> - Discovery messages for <code>.Rule.ps1</code> files and rule modules.</li> <li><code>[Discovery.Rule]</code> - Discovery messages for individual rules within <code>.Rule.ps1</code> files.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingLimitDebug parameter\n$option = New-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n</code></pre> <pre><code># PowerShell: Using the Logging.LimitDebug hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitDebug' = Rule1, Rule2 };\n</code></pre> <pre><code># PowerShell: Using the LoggingLimitDebug parameter to set YAML\nSet-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n</code></pre> <pre><code># YAML: Using the logging/limitDebug property\nlogging:\n  limitDebug:\n  - Rule1\n  - Rule2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitverbose","title":"Logging.LimitVerbose","text":"<p>Limits verbose messages to a list of named verbose scopes.</p> <p>When using the <code>-Verbose</code> switch or preference variable, by default PSRule cmdlets log all verbose output. When using verbose output for troubleshooting a specific rule, it may be helpful to limit verbose messages to a specific rule.</p> <p>To identify a rule to include in verbose output use the rule name.</p> <p>The following built-in scopes exist in addition to rule names:</p> <ul> <li><code>[Discovery.Source]</code> - Discovery messages for <code>.Rule.ps1</code> files and rule modules.</li> <li><code>[Discovery.Rule]</code> - Discovery messages for individual rules within <code>.Rule.ps1</code> files.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingLimitVerbose parameter\n$option = New-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n</code></pre> <pre><code># PowerShell: Using the Logging.LimitVerbose hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitVerbose' = Rule1, Rule2 };\n</code></pre> <pre><code># PowerShell: Using the LoggingLimitVerbose parameter to set YAML\nSet-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n</code></pre> <pre><code># YAML: Using the logging/limitVerbose property\nlogging:\n  limitVerbose:\n  - Rule1\n  - Rule2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulefail","title":"Logging.RuleFail","text":"<p>When an object fails a rule condition the results are written to output as a structured object marked with the outcome of Fail. If the rule executed successfully regardless of outcome no other informational messages are shown by default.</p> <p>In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages or abort the CI process if one or more Fail outcomes are returned.</p> <p>By settings this option, error, warning or information messages will be generated for each rule fail outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).</p> <p>The following streams available:</p> <ul> <li>None</li> <li>Error</li> <li>Warning</li> <li>Information</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingRuleFail parameter\n$option = New-PSRuleOption -LoggingRuleFail Error;\n</code></pre> <pre><code># PowerShell: Using the Logging.RuleFail hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RuleFail' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the LoggingRuleFail parameter to set YAML\nSet-PSRuleOption -LoggingRuleFail Error;\n</code></pre> <pre><code># YAML: Using the logging/ruleFail property\nlogging:\n  ruleFail: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulepass","title":"Logging.RulePass","text":"<p>When an object passes a rule condition the results are written to output as a structured object marked with the outcome of Pass. If the rule executed successfully regardless of outcome no other informational messages are shown by default.</p> <p>In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages.</p> <p>By settings this option, error, warning or information messages will be generated for each rule pass outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).</p> <p>The following streams available:</p> <ul> <li>None</li> <li>Error</li> <li>Warning</li> <li>Information</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingRulePass parameter\n$option = New-PSRuleOption -LoggingRulePass Information;\n</code></pre> <pre><code># PowerShell: Using the Logging.RulePass hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RulePass' = 'Information' };\n</code></pre> <pre><code># PowerShell: Using the LoggingRulePass parameter to set YAML\nSet-PSRuleOption -LoggingRulePass Information;\n</code></pre> <pre><code># YAML: Using the logging/rulePass property\nlogging:\n  rulePass: Information\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputas","title":"Output.As","text":"<p>Configures the type of results to produce.</p> <p>This option only applies to <code>Invoke-PSRule</code> and <code>Assert-PSRule</code>. <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> also include a <code>-As</code> parameter to set this option at runtime. If specified, the <code>-As</code> parameter take precedence, over this option.</p> <p>The following options are available:</p> <ul> <li>Detail - Return a record per rule per object.</li> <li>Summary - Return summary results.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputAs parameter\n$option = New-PSRuleOption -OutputAs Summary;\n</code></pre> <pre><code># PowerShell: Using the Output.As hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.As' = 'Summary' };\n</code></pre> <pre><code># PowerShell: Using the OutputAs parameter to set YAML\nSet-PSRuleOption -OutputAs Summary;\n</code></pre> <pre><code># YAML: Using the output/as property\noutput:\n  as: Summary\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_AS=Summary\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_AS: Summary\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_AS\n  value: Summary\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputbanner","title":"Output.Banner","text":"<p>The information displayed for PSRule banner. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <p>The following information can be shown or hidden by configuring this option.</p> <ul> <li><code>Title</code> (1) - Shows the PSRule title ASCII text.</li> <li><code>Source</code> (2) - Shows rules module versions used in this run.</li> <li><code>SupportLinks</code> (4) - Shows supporting links for PSRule and rules modules.</li> <li><code>RepositoryInfo</code> (8) - Show information about the repository where PSRule is being run from.</li> </ul> <p>Additionally the following rollup options exist:</p> <ul> <li><code>Default</code> - Shows <code>Title</code>, <code>Source</code>, <code>SupportLinks</code>, <code>RepositoryInfo</code>. This is the default option.</li> <li><code>Minimal</code> - Shows <code>Source</code>.</li> </ul> <p>This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example <code>6</code> would show <code>Source</code>, and <code>SupportLinks</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputBanner parameter\n$option = New-PSRuleOption -OutputBanner Minimal;\n</code></pre> <pre><code># PowerShell: Using the Output.Banner hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Banner' = 'Minimal' };\n</code></pre> <pre><code># PowerShell: Using the OutputBanner parameter to set YAML\nSet-PSRuleOption -OutputBanner Minimal;\n</code></pre> <pre><code># YAML: Using the output/banner property\noutput:\n  banner: Minimal\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_BANNER=Minimal\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_BANNER: Minimal\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_BANNER\n  value: Minimal\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputculture","title":"Output.Culture","text":"<p>Specified the name of one or more cultures to use for generating output. When multiple cultures are specified, the first matching culture will be used. If a culture is not specified, PSRule will use the current PowerShell culture.</p> <p>PSRule cmdlets also include a <code>-Culture</code> parameter to set this option at runtime. If specified, the <code>-Culture</code> parameter take precedence, over this option.</p> <p>To get a list of cultures use the <code>Get-Culture -ListAvailable</code> cmdlet.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputCulture parameter\n$option = New-PSRuleOption -OutputCulture 'en-AU';\n</code></pre> <pre><code># PowerShell: Using the Output.Culture hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Culture' = 'en-AU' };\n</code></pre> <pre><code># PowerShell: Using the OutputCulture parameter to set YAML\nSet-PSRuleOption -OutputCulture 'en-AU', 'en-US';\n</code></pre> <pre><code># YAML: Using the output/culture property\noutput:\n  culture: [ 'en-AU', 'en-US' ]\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_CULTURE=en-AU;en-US\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_CULTURE: en-AU;en-US\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_CULTURE\n  value: en-AU;en-US\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputencoding","title":"Output.Encoding","text":"<p>Configures the encoding used when output is written to file. This option has no affect when <code>Output.Path</code> is not set.</p> <p>The following encoding options are available:</p> <ul> <li>Default</li> <li>UTF-8</li> <li>UTF-7</li> <li>Unicode</li> <li>UTF-32</li> <li>ASCII</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputEncoding parameter\n$option = New-PSRuleOption -OutputEncoding UTF8;\n</code></pre> <pre><code># PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Encoding' = 'UTF8' };\n</code></pre> <pre><code># PowerShell: Using the OutputEncoding parameter to set YAML\nSet-PSRuleOption -OutputEncoding UTF8;\n</code></pre> <pre><code># YAML: Using the output/encoding property\noutput:\n  encoding: UTF8\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_ENCODING=UTF8\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_ENCODING: UTF8\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_ENCODING\n  value: UTF8\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputfooter","title":"Output.Footer","text":"<p>The information displayed for PSRule footer. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <p>The following information can be shown or hidden by configuring this option.</p> <ul> <li><code>RuleCount</code> (1) - Shows a summary of rules processed.</li> <li><code>RunInfo</code> (2) - Shows information about the run.</li> <li><code>OutputFile</code> (4) - Shows information about the output file if an output path is set.</li> </ul> <p>Additionally the following rollup options exist:</p> <ul> <li><code>Default</code> - Shows <code>RuleCount</code>, <code>RunInfo</code>, and <code>OutputFile</code>. This is the default option.</li> </ul> <p>This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example <code>3</code> would show <code>RunInfo</code>, and <code>RuleCount</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputFooter parameter\n$option = New-PSRuleOption -OutputFooter RuleCount;\n</code></pre> <pre><code># PowerShell: Using the Output.Footer hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Footer' = 'RuleCount' };\n</code></pre> <pre><code># PowerShell: Using the OutputFooter parameter to set YAML\nSet-PSRuleOption -OutputFooter RuleCount;\n</code></pre> <pre><code># YAML: Using the output/footer property\noutput:\n  footer: RuleCount\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_FOOTER=RuleCount\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_FOOTER: RuleCount\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FOOTER\n  value: RuleCount\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputformat","title":"Output.Format","text":"<p>Configures the format that results will be presented in. This option applies to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code>, <code>Get-PSRule</code> and <code>Get-PSRuleBaseline</code>. This options is ignored by other cmdlets.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults.   This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> <li>Markdown - Output is serialized as Markdown.</li> <li>NUnit3 - Output is serialized as NUnit3 (XML).</li> <li>Csv - Output is serialized as a comma-separated values (CSV).<ul> <li>The following columns are included for <code>Detail</code> output: RuleName, TargetName, TargetType, Outcome, OutcomeReason, Synopsis, Recommendation</li> <li>The following columns are included for <code>Summary</code> output: RuleName, Pass, Fail, Outcome, Synopsis, Recommendation</li> </ul> </li> <li>Wide -  Output is presented using the wide table format, which includes reason and wraps columns.</li> <li>Sarif - Output is serialized as SARIF.</li> </ul> <p>The Wide format is ignored by <code>Assert-PSRule</code>. <code>Get-PSRule</code> only accepts <code>None</code>, <code>Wide</code>, <code>Yaml</code> and <code>Json</code>. Usage of other formats are treated as <code>None</code>.</p> <p>The <code>Get-PSRuleBaseline</code> cmdlet only accepts <code>None</code> or <code>Yaml</code>. The <code>Export-PSRuleBaseline</code> cmdlet only accepts <code>Yaml</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputFormat parameter\n$option = New-PSRuleOption -OutputFormat Yaml;\n</code></pre> <pre><code># PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Format' = 'Yaml' };\n</code></pre> <pre><code># PowerShell: Using the OutputFormat parameter to set YAML\nSet-PSRuleOption -OutputFormat Yaml;\n</code></pre> <pre><code># YAML: Using the output/format property\noutput:\n  format: Yaml\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_FORMAT=Yaml\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_FORMAT: Yaml\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FORMAT\n  value: Yaml\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputoutcome","title":"Output.Outcome","text":"<p>Filters output to include results with the specified outcome. The following outcome options are available:</p> <ul> <li><code>None</code> (0) - Results for rules that did not get processed are returned.   This include rules that have been suppressed or were not run against a target object.</li> <li><code>Fail</code> (1) - Results for rules that failed are returned.</li> <li><code>Pass</code> (2)  - Results for rules that passed are returned.</li> <li><code>Error</code> (4) - Results for rules that raised an error are returned.</li> </ul> <p>Additionally the following rollup options exist:</p> <ul> <li><code>Processed</code> - Results for rules with the <code>Fail</code>, <code>Pass</code>, or <code>Error</code> outcome. This is the default option.</li> <li><code>Problem</code> - Results for rules with the <code>Fail</code>, or <code>Error</code> outcome.</li> <li><code>All</code> - All results for rules are returned.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputOutcome parameter\n$option = New-PSRuleOption -OutputOutcome Fail;\n</code></pre> <pre><code># PowerShell: Using the Output.Outcome hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Outcome' = 'Fail' };\n</code></pre> <pre><code># PowerShell: Using the OutputOutcome parameter to set YAML\nSet-PSRuleOption -OutputOutcome Fail;\n</code></pre> <pre><code># YAML: Using the output/outcome property\noutput:\n  outcome: 'Fail'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_OUTCOME=Fail\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_OUTCOME: Fail\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_OUTCOME\n  value: Fail\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputpath","title":"Output.Path","text":"<p>Specifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.</p> <p>This option only applies to <code>Invoke-PSRule</code>. <code>Invoke-PSRule</code> also includes a parameter <code>-OutputPath</code> to set this option at runtime. If specified, the <code>-OutputPath</code> parameter take precedence, over this option.</p> <p>Syntax:</p> <pre><code>output:\n  path: string\n</code></pre> <p>Default:</p> <pre><code>output:\n  path: null\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputPath parameter\n$option = New-PSRuleOption -OutputPath 'out/results.yaml';\n</code></pre> <pre><code># PowerShell: Using the Output.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Path' = 'out/results.yaml' };\n</code></pre> <pre><code># PowerShell: Using the OutputPath parameter to set YAML\nSet-PSRuleOption -OutputPath 'out/results.yaml';\n</code></pre> <pre><code># YAML: Using the output/path property\noutput:\n  path: 'out/results.yaml'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_PATH=out/results.yaml\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_PATH: out/results.yaml\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_PATH\n  value: out/results.yaml\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputsarifproblemsonly","title":"Output.SarifProblemsOnly","text":"<p>Determines if SARIF output only includes rules with fail or error outcomes. By default, only rules with fail or error outcomes are included for compatibility with external tools. To include rules with pass outcomes, set this option to <code>false</code>. This option only applies when the output format is <code>Sarif</code>.</p> <p>Syntax:</p> <pre><code>output:\n  sarifProblemsOnly: boolean\n</code></pre> <p>Default:</p> <pre><code>output:\n  sarifProblemsOnly: true\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputSarifProblemsOnly parameter\n$option = New-PSRuleOption -OutputSarifProblemsOnly $False;\n</code></pre> <pre><code># PowerShell: Using the Output.SarifProblemsOnly hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.SarifProblemsOnly' = $False };\n</code></pre> <pre><code># PowerShell: Using the OutputSarifProblemsOnly parameter to set YAML\nSet-PSRuleOption -OutputSarifProblemsOnly $False;\n</code></pre> <pre><code># YAML: Using the output/sarifProblemsOnly property\noutput:\n  sarifProblemsOnly: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_SARIFPROBLEMSONLY=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_SARIFPROBLEMSONLY: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_SARIFPROBLEMSONLY\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputstyle","title":"Output.Style","text":"<p>Configures the style that results will be presented in.</p> <p>This option only applies to output generated from <code>Assert-PSRule</code>. <code>Assert-PSRule</code> also include a parameter <code>-Style</code> to set this option at runtime. If specified, the <code>-Style</code> parameter takes precedence, over this option.</p> <p>The following styles are available:</p> <ul> <li><code>Client</code> - Output is written to the host directly in green/ red to indicate outcome.</li> <li><code>Plain</code> - Output is written as an unformatted string. This option can be redirected to a file.</li> <li><code>AzurePipelines</code> - Output is written for integration Azure Pipelines.</li> <li><code>GitHubActions</code> - Output is written for integration GitHub Actions.</li> <li><code>VisualStudioCode</code> - Output is written for integration with Visual Studio Code.</li> <li><code>Detect</code> - Output style will be detected by checking the environment variables. This is the default.</li> </ul> <p>Detect uses the following logic:</p> <ol> <li>If the <code>TF_BUILD</code> environment variable is set to <code>true</code>, <code>AzurePipelines</code> will be used.</li> <li>If the <code>GITHUB_ACTIONS</code> environment variable is set to <code>true</code>, <code>GitHubActions</code> will be used.</li> <li>If the <code>TERM_PROGRAM</code> environment variable is set to <code>vscode</code>, <code>VisualStudioCode</code> will be used.</li> <li>Use <code>Client</code>.</li> </ol> <p>Syntax:</p> <pre><code>output:\n  style: string\n</code></pre> <p>Default:</p> <pre><code>output:\n  style: Detect\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputStyle parameter\n$option = New-PSRuleOption -OutputStyle AzurePipelines;\n</code></pre> <pre><code># PowerShell: Using the Output.Style hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Style' = 'AzurePipelines' };\n</code></pre> <pre><code># PowerShell: Using the OutputStyle parameter to set YAML\nSet-PSRuleOption -OutputFormat AzurePipelines;\n</code></pre> <pre><code># YAML: Using the output/style property\noutput:\n  style: AzurePipelines\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=AzurePipelines\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_STYLE: AzurePipelines\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n  value: AzurePipelines\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjobsummarypath","title":"Output.JobSummaryPath","text":"<p> v2.6.0</p> <p>Configures the file path a job summary will be written to when using <code>Assert-PSRule</code>. A job summary is a markdown file that summarizes the results of a job. When not specified, a job summary will not be generated.</p> <p>Syntax:</p> <pre><code>output:\n  jobSummaryPath: string\n</code></pre> <p>Default:</p> <pre><code>output:\n  jobSummaryPath: null\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputJobSummaryPath parameter\n$option = New-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n</code></pre> <pre><code># PowerShell: Using the Output.JobSummaryPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JobSummaryPath' = 'reports/summary.md' };\n</code></pre> <pre><code># PowerShell: Using the OutputJobSummaryPath parameter to set YAML\nSet-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n</code></pre> <pre><code># YAML: Using the output/jobSummaryPath property\noutput:\n  jobSummaryPath: 'reports/summary.md'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_JOBSUMMARYPATH='reports/summary.md'\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JOBSUMMARYPATH = 'reports/summary.md';\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_JOBSUMMARYPATH: reports/summary.md\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JOBSUMMARYPATH\n  value: reports/summary.md\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjsonindent","title":"Output.JsonIndent","text":"<p>Configures the number of spaces to indent JSON properties and elements. The default number of spaces is 0.</p> <p>This option applies to output generated from <code>-OutputFormat Json</code> for <code>Get-PSRule</code> and <code>Invoke-PSRule</code>. This option also applies to output generated from <code>-OutputPath</code> for <code>Assert-PSRule</code>.</p> <p>The range of indentation accepts a minimum of 0 (machine first) spaces and a maximum of 4 spaces.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputJsonIndent parameter\n$option = New-PSRuleOption -OutputJsonIndent 2;\n</code></pre> <pre><code># PowerShell: Using the Output.JsonIndent hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JsonIndent' = 2 };\n</code></pre> <pre><code># PowerShell: Using the OutputJsonIndent parameter to set YAML\nSet-PSRuleOption -OutputJsonIndent 2;\n</code></pre> <pre><code># YAML: Using the output/jsonIndent property\noutput:\n  jsonIndent: 2\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_JSONINDENT=2\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JSONINDENT = 2;\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_JSONINDENT: 2\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JSONINDENT\n  value: 2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositorybaseref","title":"Repository.BaseRef","text":"<p>This option is used for specify the base branch for pull requests. When evaluating changes files only PSRule uses this option for comparison with the current branch. By default, the base ref is detected from environment variables set by the build system.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RepositoryBaseRef parameter\n$option = New-PSRuleOption -RepositoryBaseRef 'main';\n</code></pre> <pre><code># PowerShell: Using the Repository.BaseRef hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.BaseRef' = 'main' };\n</code></pre> <pre><code># PowerShell: Using the RepositoryBaseRef parameter to set YAML\nSet-PSRuleOption -RepositoryBaseRef 'main';\n</code></pre> <pre><code># YAML: Using the repository/baseRef property\nrepository:\n  baseRef: main\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_REPOSITORY_BASEREF='main'\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_BASEREF = 'main';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositoryurl","title":"Repository.Url","text":"<p>This option can be configured to set the repository URL reported in output. By default, the repository URL is detected from environment variables set by the build system.</p> <ul> <li>In GitHub Actions, the repository URL is detected from the <code>GITHUB_REPOSITORY</code> environment variable.</li> <li>In Azure Pipelines, the repository URL is detected from the <code>BUILD_REPOSITORY_URI</code> environment variable.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RepositoryUrl parameter\n$option = New-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n</code></pre> <pre><code># PowerShell: Using the Repository.Url hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.Url' = 'https://github.com/microsoft/PSRule' };\n</code></pre> <pre><code># PowerShell: Using the RepositoryUrl parameter to set YAML\nSet-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n</code></pre> <pre><code># YAML: Using the repository/url property\nrepository:\n  url: 'https://github.com/microsoft/PSRule'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_REPOSITORY_URL='https://github.com/microsoft/PSRule'\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_URL = 'https://github.com/microsoft/PSRule';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#requires","title":"Requires","text":"<p>Specifies module version constraints for running PSRule. When set PSRule will error if a module version is used that does not satisfy the requirements. The format for version constraints are the same as the <code>Version</code> assertion method. See [about_PSRule_Assert] for more information.</p> <p>Module version constraints a not enforced prior to PSRule v0.19.0.</p> <p>The version constraint for a rule module is enforced when the module is included with <code>-Module</code>. A version constraint does not require a rule module to be included. Use the <code>Include.Module</code> option to automatically include a rule module.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Requires.module hashtable key\n$option = New-PSRuleOption -Option @{ 'Requires.PSRule' = '&gt;=1.0.0' };\n</code></pre> <pre><code># YAML: Using the requires property\nrequires:\n  PSRule: '&gt;=1.0.0'                 # Require v1.0.0 or greater.\n  PSRule.Rules.Azure: '&gt;=1.0.0'     # Require v1.0.0 or greater.\n  PSRule.Rules.CAF: '@pre &gt;=0.1.0'  # Require stable or pre-releases v0.1.0 or greater.\n</code></pre> <p>This option can be configured using environment variables. To specify a module version constraint, prefix the module name with <code>PSRULE_REQUIRES_</code>. When the module name includes a dot (<code>.</code>) use an underscore (<code>_</code>) instead.</p> <pre><code># Bash: Using environment variable\nexport PSRULE_REQUIRES_PSRULE='&gt;=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_AZURE='&gt;=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_CAF='@pre &gt;=0.1.0'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_REQUIRES_PSRULE: '&gt;=1.0.0'\n  PSRULE_REQUIRES_PSRULE_RULES_AZURE: '&gt;=1.0.0'\n  PSRULE_REQUIRES_PSRULE_RULES_CAF: '@pre &gt;=0.1.0'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_REQUIRES_PSRULE\n  value: '&gt;=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_AZURE\n  value: '&gt;=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_CAF\n  value: '@pre &gt;=0.1.0'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#rulebaseline","title":"Rule.Baseline","text":"<p>The name of a default baseline to use for the module. Currently this option can only be set within a module configuration resource.</p> <p>For example:</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  rule:\n    baseline: Enterprise.Baseline1\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleinclude","title":"Rule.Include","text":"<p>The name of specific rules to evaluate. If this option is not specified all rules in search paths will be evaluated.</p> <p>This option can be overridden at runtime by using the <code>-Name</code> cmdlet parameter.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Rule.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Include' = 'Rule1','Rule2' };\n</code></pre> <pre><code># YAML: Using the rule/include property\nrule:\n  include:\n  - Rule1\n  - Rule2\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_RULE_INCLUDE='Rule1;Rule2'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_RULE_INCLUDE: 'Rule1;Rule2'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDE\n  value: 'Rule1;Rule2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleincludelocal","title":"Rule.IncludeLocal","text":"<p>Automatically include all local rules in the search path unless they have been explicitly excluded. This option will include local rules even when they do not match <code>Rule.Include</code> or <code>Rule.Tag</code> filters. By default, local rules will be filtered with <code>Rule.Include</code> and <code>Rule.Tag</code> filters.</p> <p>This option is useful when you want to include local rules not included in a baseline.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RuleIncludeLocal parameter\n$option = New-PSRuleOption -RuleIncludeLocal $True;\n</code></pre> <pre><code># PowerShell: Using the Rule.IncludeLocal hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.IncludeLocal' = $True };\n</code></pre> <pre><code># PowerShell: Using the RuleIncludeLocal parameter to set YAML\nSet-PSRuleOption -RuleIncludeLocal $True;\n</code></pre> <pre><code># YAML: Using the rule/includeLocal property\nrule:\n  includeLocal: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_RULE_INCLUDELOCAL=true\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_RULE_INCLUDELOCAL: true\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDELOCAL\n  value: true\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleexclude","title":"Rule.Exclude","text":"<p>The name of specific rules to exclude from being evaluated. This will exclude rules specified by <code>Rule.Include</code> or discovered from a search path.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Rule.Exclude hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Exclude' = 'Rule3','Rule4' };\n</code></pre> <pre><code># YAML: Using the rule/exclude property\nrule:\n  exclude:\n  - Rule3\n  - Rule4\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_RULE_EXCLUDE='Rule3;Rule4'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_RULE_EXCLUDE: 'Rule3;Rule4'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_EXCLUDE\n  value: 'Rule3;Rule4'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruletag","title":"Rule.Tag","text":"<p>A set of required key value pairs (tags) that rules must have applied to them to be included.</p> <p>Multiple values can be specified for the same tag. When multiple values are used, only one must match.</p> <p>This option can be overridden at runtime by using the <code>-Tag</code> cmdlet parameter.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Rule.Tag hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Tag' = @{ severity = 'Critical','Warning' } };\n</code></pre> <pre><code># YAML: Using the rule/tag property\nrule:\n  tag:\n    severity: Critical\n</code></pre> <pre><code># YAML: Using the rule/tag property, with multiple values\nrule:\n  tag:\n    severity:\n    - Critical\n    - Warning\n</code></pre> <p>In the example above, rules must have a tag of <code>severity</code> set to either <code>Critical</code> or <code>Warning</code> to be included.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#suppression","title":"Suppression","text":"<p>In certain circumstances it may be necessary to exclude or suppress rules from processing objects that are in a known failed state.</p> <p>PSRule allows objects to be suppressed for a rule by TargetName. Objects that are suppressed are not processed by the rule at all but will continue to be processed by other rules.</p> <p>Rule suppression complements pre-filtering and pre-conditions.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the SuppressTargetName option with a hashtable\n$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\n</code></pre> <pre><code># YAML: Using the suppression property\nsuppression:\n  storageAccounts.UseHttps:\n    targetName:\n    - TestObject1\n    - TestObject3\n</code></pre> <p>In both of the above examples, <code>TestObject1</code> and <code>TestObject3</code> have been suppressed from being processed by a rule named <code>storageAccounts.UseHttps</code>.</p> <p>When to use rule suppression:</p> <ul> <li>A temporary exclusion for an object that is in a known failed state.</li> </ul> <p>When not to use rule suppression:</p> <ul> <li>An object should never be processed by any rule. Pre-filter the pipeline instead.</li> <li>The rule is not applicable because the object is the wrong type. Use pre-conditions on the rule instead.</li> </ul> <p>An example of pre-filtering:</p> <pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge'; Type = 'Equipment'; Category = 'White goods'; };\n$items += [PSCustomObject]@{ Name = 'Apple'; Type = 'Food'; Category = 'Produce'; };\n$items += [PSCustomObject]@{ Name = 'Carrot'; Type = 'Food'; Category = 'Produce'; };\n\n# Example of pre-filtering, only food items are sent to Invoke-PSRule\n$items | Where-Object { $_.Type -eq 'Food' } | Invoke-PSRule;\n</code></pre> <p>An example of pre-conditions:</p> <pre><code># A rule with a pre-condition to only process produce\nRule 'isFruit' -If { $TargetObject.Category -eq 'Produce' } {\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#example-ps-ruleyaml","title":"Example ps-rule.yaml","text":"<pre><code>#\n# PSRule example configuration\n#\n\n# Configures the repository\nrepository:\n  url: https://github.com/microsoft/PSRule\n  baseRef: main\n\n# Configure required module versions\nrequires:\n  PSRule.Rules.Azure: '&gt;=1.1.0'\n\n# Configure convention options\nconvention:\n  include:\n  - 'Convention1'\n\n# Configure execution options\nexecution:\n  hashAlgorithm: SHA256\n  duplicateResourceId: Warn\n  languageMode: ConstrainedLanguage\n  suppressionGroupExpired: Error\n  restrictScriptSource: ModuleOnly\n\n# Configure include options\ninclude:\n  module:\n  - 'PSRule.Rules.Azure'\n  path: [ ]\n\n# Configures input options\ninput:\n  format: Yaml\n  ignoreGitPath: false\n  ignoreObjectSource: true\n  ignoreRepositoryCommon: false\n  ignoreUnchangedPath: true\n  objectPath: items\n  pathIgnore:\n  - '*.Designer.cs'\n  targetType:\n  - Microsoft.Compute/virtualMachines\n  - Microsoft.Network/virtualNetworks\n\n# Configures outcome logging options\nlogging:\n  limitDebug:\n  - Rule1\n  - Rule2\n  limitVerbose:\n  - Rule1\n  - Rule2\n  ruleFail: Error\n  rulePass: Information\n\noutput:\n  as: Summary\n  banner: Minimal\n  culture:\n  - en-US\n  encoding: UTF8\n  footer: RuleCount\n  format: Json\n  jobSummaryPath: reports/summary.md\n  outcome: Fail\n  sarifProblemsOnly: false\n  style: GitHubActions\n\n# Configure rule suppression\nsuppression:\n  storageAccounts.UseHttps:\n    targetName:\n    - TestObject1\n    - TestObject3\n\n# Configure baseline options\nbinding:\n  field:\n    id:\n    - ResourceId\n    - AlternativeId\n  ignoreCase: false\n  nameSeparator: '::'\n  preferTargetInfo: true\n  targetName:\n  - ResourceName\n  - AlternateName\n  targetType:\n  - ResourceType\n  - kind\n  useQualifiedName: true\n\nconfiguration:\n  appServiceMinInstanceCount: 2\n\nrule:\n  include:\n  - rule1\n  - rule2\n  includeLocal: true\n  exclude:\n  - rule3\n  - rule4\n  tag:\n    severity:\n    - Critical\n    - Warning\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#default-ps-ruleyaml","title":"Default ps-rule.yaml","text":"<pre><code>#\n# PSRule defaults\n#\n\n# Note: Only properties that differ from the default values need to be specified.\n\n# Configure required module versions\nrequires: { }\n\n# Configure convention options\nconvention:\n  include: [ ]\n\n# Configure execution options\nexecution:\n  hashAlgorithm: SHA512\n  aliasReference: Warn\n  duplicateResourceId: Error\n  invariantCulture: Warn\n  languageMode: FullLanguage\n  initialSessionState: BuiltIn\n  restrictScriptSource: Unrestricted\n  ruleInconclusive: Warn\n  ruleSuppressed: Warn\n  suppressionGroupExpired: Warn\n  unprocessedObject: Warn\n\n# Configure include options\ninclude:\n  module: [ ]\n  path:\n  - '.ps-rule/'\n\n# Configures input options\ninput:\n  format: Detect\n  ignoreGitPath: true\n  ignoreObjectSource: false\n  ignoreRepositoryCommon: true\n  ignoreUnchangedPath: false\n  objectPath: null\n  pathIgnore: [ ]\n  targetType: [ ]\n\n# Configures outcome logging options\nlogging:\n  limitDebug: [ ]\n  limitVerbose: [ ]\n  ruleFail: None\n  rulePass: None\n\noutput:\n  as: Detail\n  banner: Default\n  culture: [ ]\n  encoding: Default\n  footer: Default\n  format: None\n  jobSummaryPath: null\n  outcome: Processed\n  sarifProblemsOnly: true\n  style: Detect\n\n# Configure rule suppression\nsuppression: { }\n\n# Configure baseline options\nbinding:\n  field: { }\n  ignoreCase: true\n  nameSeparator: '/'\n  preferTargetInfo: false\n  targetName:\n  - TargetName\n  - Name\n  targetType:\n  - PSObject.TypeNames[0]\n  useQualifiedName: false\n\nconfiguration: { }\n\nrule:\n  include: [ ]\n  includeLocal: false\n  exclude: [ ]\n  tag: { }\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> <li>New-PSRuleOption</li> <li>Set-PSRuleOption</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/","title":"Rules","text":"<p>Describes PSRule rules including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input either from a file or PowerShell pipeline. The PowerShell pipeline only available when running PSRule directly. PSRule can also be run from a continuous integration (CI) pipeline or Visual Studio Code. When using these methods, the PowerShell pipeline is not available.</p> <p>To evaluate an object PSRule can use rules defined in script or YAML.</p> <p>When using script rules:</p> <ul> <li>Each rule is defined PowerShell within a <code>.Rule.ps1</code> file by using a <code>Rule</code> block.</li> <li>PowerShell variables, functions, and cmdlets can be used just like regular PowerShell scripts.</li> <li>Built-in assertion helpers can be used to quickly build out rules.</li> <li>Pre-conditions can be defined with using a script block, type binding, or YAML-based selector.</li> </ul> <p>To learn more about assertion helpers see about_PSRule_Assert.</p> <p>When using YAML rules:</p> <ul> <li>Each rule is defined in a <code>.Rule.yaml</code> file by using the <code>Rule</code> resource.</li> <li>YAML-based expressions can be used.</li> <li>Pre-conditions can be defined with using a type binding, or YAML-based selector.</li> </ul> <p>To learn more about YAML-based expressions see about_PSRule_Expressions.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#using-pre-conditions","title":"Using pre-conditions","text":"<p>Pre-conditions are used to determine if a rule should be executed. While pre-conditions are not required for each rule, it is a good practice to define them. If a rule does not specify a pre-condition it may be executed against an object it does not expect.</p> <p>Pre-conditions come in three forms:</p> <ul> <li>Script - A PowerShell script block that is executed and if true will cause the rule to be executed.   Script block pre-conditions only work with script rules.   To use a script block pre-condition, specify the <code>-If</code> script parameter on the <code>Rule</code> block.</li> <li>Type - A type string that is compared against the bound object type.   When the type matches the rule will be executed.   To use a type pre-conditions, specify the <code>-Type</code> script parameter or <code>type</code> YAML/JSON property.</li> <li>Selector - A YAML/JSON based expression that is evaluated against the object.   When the expression matches the rule will be executed.   To use a selector pre-conditions, specify the <code>-With</code> script parameter or <code>with</code> YAML/JSON property.</li> </ul> <p>Different forms of pre-conditions can be combined. When combining pre-conditions, different forms must be all true (logical AND). i.e. Script AND Type AND Selector must be all be true for the rule to be executed.</p> <p>Multiple Type and Selector pre-conditions can be specified. If multiple Type and Selector pre-conditions are specified, only one must be true (logical OR).</p> <p>For example:</p> <pre><code># Synopsis: An example script rule with pre-conditions.\nRule 'ScriptRule' -If { $True } -Type 'CustomType1', 'CustomType2' -With 'Selector.1', 'Selector.2' {\n    # Rule condition\n}\n</code></pre> <pre><code>---\n# Synopsis: An example YAML rule with pre-conditions.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'YamlRule'\nspec:\n  type:\n  - 'CustomType1'\n  - 'CustomType2'\n  with:\n  - 'Selector.1'\n  - 'Selector.2'\n  condition: { }\n</code></pre> <pre><code>[\n  {\n    // Synopsis: An example YAML rule with pre-conditions.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Rule\",\n    \"metadata\": {\n      \"name\": \"YamlRule\"\n    },\n    \"spec\": {\n      \"type\": [\n        \"CustomType1\",\n        \"CustomType2\"\n      ],\n      \"with\": [\n        \"Selector.1\",\n        \"Selector.2\"\n      ],\n      \"condition\": {}\n    }\n  }\n]\n</code></pre> <p>Pre-conditions are evaluated in the following order: Selector, Type, then Script.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-script-rules","title":"Defining script rules","text":"<p>To define a script rule use the <code>Rule</code> keyword followed by a name and a pair of squiggly brackets <code>{</code>. Within the <code>{ }</code> one or more conditions can be used. Script rule must be defined within <code>.Rule.ps1</code> files. Multiple rules can be defined in a single file by creating multiple <code>Rule</code> blocks. Rule blocks can not be nested within each other.</p> <p>Within the <code>Rule</code> block, define one or more conditions to determine pass or fail of the rule.</p> <p>Syntax:</p> <pre><code>Rule [-Name] &lt;string&gt; [-Tag &lt;hashtable&gt;] [-When &lt;string[]&gt;] [-Type &lt;string[]&gt;] [-If &lt;scriptBlock&gt;] [-DependsOn &lt;string[]&gt;] [-Configure &lt;hashtable&gt;] [-ErrorAction &lt;ActionPreference&gt;] [-Body] {\n    ...\n}\n</code></pre> <p>Example:</p> <pre><code># Synopsis: Use a Standard load-balancer with AKS clusters.\nRule 'Azure.AKS.StandardLB' -Type 'Microsoft.ContainerService/managedClusters' -Tag @{ release = 'GA'; ruleSet = '2020_06' } {\n    $Assert.HasFieldValue($TargetObject, 'Properties.networkProfile.loadBalancerSku', 'standard');\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-yaml-rules","title":"Defining YAML rules","text":"<p>To define a YAML rule use the <code>Rule</code> resource in a YAML file. Each rule must be defined within a <code>.Rule.yaml</code> file following a standard schema. Multiple rules can be defined in a single YAML file by separating each rule with a <code>---</code>.</p> <p>Within the <code>Rule</code> resource, the <code>condition</code> property specifies conditions to pass or fail the rule.</p> <p>Syntax:</p> <pre><code>---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: '{{ Name }}'\n  tags: { }\nspec:\n  type: [ ]\n  with: [ ]\n  condition: { }\n</code></pre> <p>Example:</p> <pre><code>---\n# Synopsis: Use a Standard load-balancer with AKS clusters.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Azure.AKS.StandardLB'\n  tags:\n    release: 'GA'\n    ruleSet: '2020_06'\nspec:\n  type:\n  - Microsoft.ContainerService/managedClusters\n  condition:\n    field: 'Properties.networkProfile.loadBalancerSku'\n    equals: 'standard'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-json-rules","title":"Defining JSON rules","text":"<p>To define a JSON rule use the <code>Rule</code> resource in a JSON file. Each rule must be defined within a <code>.Rule.jsonc</code> file following a standard schema. One or more rules can be defined in a single JSON array separating each rule in a JSON object.</p> <p>Within the <code>Rule</code> resource, the <code>condition</code> property specifies conditions to pass or fail the rule.</p> <p>Rules can also be defined within <code>.json</code> files. We recommend using <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>Syntax:</p> <pre><code>[\n  {\n    // Synopsis: {{ Synopsis }}\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Rule\",\n    \"metadata\": {\n      \"name\": \"{{ Name }}\",\n      \"tags\": {}\n    },\n    \"spec\": {\n      \"type\": [],\n      \"with\": [],\n      \"condition\": {}\n    }\n  }\n]\n</code></pre> <p>Example:</p> <pre><code>[\n  {\n    // Synopsis: Use a Standard load-balancer with AKS clusters.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Rule\",\n    \"metadata\": {\n      \"name\": \"Azure.AKS.StandardLB\",\n      \"tags\": {\n        \"release\": \"GA\",\n        \"ruleSet\": \"2020_06\"\n      }\n    },\n    \"spec\": {\n      \"type\": [\n        \"Microsoft.ContainerService/managedClusters\"\n      ],\n      \"condition\": {\n        \"field\": \"Properties.networkProfile.loadBalancerSku\",\n        \"equals\": \"standard\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/","title":"Selectors","text":"<p>Describes PSRule Selectors including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When evaluating an object from input, PSRule can use selectors to perform complex matches of an object.</p> <ul> <li>A selector is a YAML/JSON based expression that evaluates an object.</li> <li>Each selector is comprised of nested conditions, operators, and comparison properties.</li> <li>Selectors must use one or more available conditions with a comparison property to evaluate the object.</li> <li>Optionally a condition can be nested in an operator.</li> <li>Operators can be nested within other operators.</li> </ul> <p>The following conditions are available:</p> <ul> <li>Contains</li> <li>Count</li> <li>Equals</li> <li>EndsWith</li> <li>Exists</li> <li>Greater</li> <li>GreaterOrEquals</li> <li>HasDefault</li> <li>HasSchema</li> <li>HasValue</li> <li>In</li> <li>IsLower</li> <li>IsString</li> <li>IsArray</li> <li>IsBoolean</li> <li>IsDateTime</li> <li>IsInteger</li> <li>IsNumeric</li> <li>IsUpper</li> <li>Less</li> <li>LessOrEquals</li> <li>Match</li> <li>NotEquals</li> <li>NotIn</li> <li>NotMatch</li> <li>SetOf</li> <li>StartsWith</li> <li>Subset</li> <li>Version</li> </ul> <p>The following operators are available:</p> <ul> <li>AllOf</li> <li>AnyOf</li> <li>Not</li> </ul> <p>The following comparison properties are available:</p> <ul> <li>Field</li> <li>Name</li> <li>Type</li> </ul> <p>To learn more about conditions, operators, and properties see about_PSRule_Expressions.</p> <p>Currently the following limitations apply:</p> <ul> <li>Selectors can evaluate:<ul> <li>Fields of the target object.</li> <li>Type and name binding of the target object by using <code>name</code> and <code>type</code> comparison properties.</li> </ul> </li> <li>State variables such has <code>$PSRule</code> can not be evaluated.</li> <li>Bound fields can not be evaluated.</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#using-selectors-as-pre-conditions","title":"Using selectors as pre-conditions","text":"<p>Selectors can be referenced by name as a rule pre-condition by using the <code>-With</code> parameter. For example:</p> <pre><code>Rule 'RuleWithSelector' -With 'BasicSelector' {\n    # Rule condition\n}\n</code></pre> <p>Selector pre-conditions can be used together with type and script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before type or script block pre-conditions.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#defining-selectors","title":"Defining selectors","text":"<p>Selectors can be defined with either YAML or JSON format, and can be included with a module or standalone <code>.Rule.yaml</code> or <code>.Rule.jsonc</code> file. In either case, define a selector within a file ending with the <code>.Rule.yaml</code> or <code>.Rule.jsonc</code> extension. A selector can be defined side-by-side with other resources such as baselines or module configurations.</p> <p>Selectors can also be defined within <code>.json</code> files. We recommend using <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>Use the following template to define a selector:</p> <pre><code>---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: '{{ Name }}'\nspec:\n  if: { }\n</code></pre> <pre><code>[\n  {\n    // Synopsis: {{ Synopsis }}\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"{{ Name }}\"\n    },\n    \"spec\": {\n      \"if\": {}\n    }\n  }\n]\n</code></pre> <p>Within the <code>if</code> object, one or more conditions or logical operators can be used.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsruleyaml","title":"Example Selectors.Rule.yaml","text":"<pre><code># Example Selectors.Rule.yaml\n---\n# Synopsis: Require the CustomValue field.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: RequireCustomValue\nspec:\n  if:\n    field: 'CustomValue'\n    exists: true\n\n---\n# Synopsis: Require a Name or AlternativeName.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: RequireName\nspec:\n  if:\n    anyOf:\n    - field: 'AlternateName'\n      exists: true\n    - field: 'Name'\n      exists: true\n\n---\n# Synopsis: Require a specific CustomValue\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: RequireSpecificCustomValue\nspec:\n  if:\n    field: 'CustomValue'\n    in:\n    - 'Value1'\n    - 'Value2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsrulejsonc","title":"Example Selectors.Rule.jsonc","text":"<pre><code>// Example Selectors.Rule.jsonc\n[\n  {\n    // Synopsis: Require the CustomValue field.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"RequireCustomValue\"\n    },\n    \"spec\": {\n      \"if\": {\n        \"field\": \"CustomValue\",\n        \"exists\": true\n      }\n    }\n  },\n  {\n    // Synopsis: Require a Name or AlternativeName.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"RequireName\"\n    },\n    \"spec\": {\n      \"if\": {\n        \"anyOf\": [\n          {\n            \"field\": \"AlternateName\",\n            \"exists\": true\n          },\n          {\n            \"field\": \"Name\",\n            \"exists\": true\n          }\n        ]\n      }\n    }\n  },\n  {\n    // Synopsis: Require a specific CustomValue\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"RequireSpecificCustomValue\"\n    },\n    \"spec\": {\n      \"if\": {\n        \"field\": \"CustomValue\",\n        \"in\": [\n          \"Value1\",\n          \"Value2\"\n        ]\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/","title":"Suppression Groups","text":"<p>Describes PSRule Suppression Groups including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When an evaluating each object, PSRule can use suppression groups to suppress rules based on a condition. Suppression groups use a Selector to determine if the rule is suppressed.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#defining-suppression-groups","title":"Defining suppression groups","text":"<p>Suppression groups can be defined using either YAML or JSON format. A suppression group can be in a standalone file or included in a module. Define suppression groups in <code>.Rule.yaml</code> or <code>.Rule.jsonc</code> files. Each suppression group may be defined individually or side-by-side with resources such as rules or baselines.</p> <p>Suppression groups can also be defined within <code>.json</code> files. We recommend using <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>Use the following template to define a suppression group:</p> <pre><code>---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: '{{ Name }}'\nspec:\n  expiresOn: null\n  rule: []\n  if: { }\n</code></pre> <pre><code>[\n  {\n    // Synopsis: {{ Synopsis }}\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"SuppressionGroup\",\n    \"metadata\": {\n      \"name\": \"{{ Name }}\"\n    },\n    \"spec\": {\n      \"expiresOn\": null,\n      \"rule\": [],\n      \"if\": {}\n    }\n  }\n]\n</code></pre> <p>Set the <code>synopsis</code> to describe the justification for the suppression. Within the <code>rule</code> array, one or more rule names can be used. If no rules are specified, suppression will occur for all rules. Within the <code>if</code> object, one or more conditions or logical operators can be used. When the <code>if</code> condition is <code>true</code> the object will be suppressed for the current rule.</p> <p>Optionally, an expiry can be set using the <code>expiresOn</code> property. When the expiry date is reached, the suppression will no longer be applied. To configure an expiry, set a RFC3339 (ISO 8601) formatted date time using the format <code>yyyy-MM-ddTHH:mm:ssZ</code>.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#documentation","title":"Documentation","text":"<p>Suppression groups can be configured with a synopsis. When set, the synopsis will be included in output for any suppression warnings that are shown. The synopsis helps provide justification for the suppression, in a short single line message. To set the synopsis, include a comment above the suppression group <code>apiVersion</code> property.</p> <p>Alternatively, a localized synopsis can be provided in a separate markdown file. See about_PSRule_Docs for details.</p> <p>Some examples of a suppression group synopsis include:</p> <ul> <li>Ignore test objects by name.</li> <li>Ignore test objects by type.</li> <li>Ignore objects with non-production tag.</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#example-suppressiongroupsruleyaml","title":"Example SuppressionGroups.Rule.yaml","text":"<pre><code># Example SuppressionGroups.Rule.yaml\n\n---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: SuppressWithTargetName\nspec:\n  rule:\n  - 'FromFile1'\n  - 'FromFile2'\n  if:\n    name: '.'\n    in:\n    - 'TestObject1'\n    - 'TestObject2'\n\n---\n# Synopsis: Ignore test objects by type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: SuppressWithTestType\nspec:\n  expiresOn: '2030-01-01T00:00:00Z'\n  rule:\n  - 'FromFile3'\n  - 'FromFile5'\n  if:\n    type: '.'\n    equals: 'TestType'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#example-suppressiongroupsrulejsonc","title":"Example SuppressionGroups.Rule.jsonc","text":"<pre><code>// Example SuppressionGroups.Rule.jsonc\n[\n  {\n    // Synopsis: Ignore test objects by name.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"SuppressionGroup\",\n    \"metadata\": {\n      \"name\": \"SuppressWithTargetName\"\n    },\n    \"spec\": {\n      \"rule\": [\n        \"FromFile1\",\n        \"FromFile2\"\n      ],\n      \"if\": {\n        \"name\": \".\",\n        \"in\": [\n          \"TestObject1\",\n          \"TestObject2\"\n        ]\n      }\n    }\n  },\n  {\n    // Synopsis: Ignore test objects by type.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"SuppressionGroup\",\n    \"metadata\": {\n      \"name\": \"SuppressWithTestType\"\n    },\n    \"spec\": {\n      \"expiresOn\": \"2030-01-01T00:00:00Z\",\n      \"rule\": [\n        \"FromFile3\",\n        \"FromFile5\"\n      ],\n      \"if\": {\n        \"type\": \".\",\n        \"equals\": \"TestType\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/","title":"Variables","text":"<p>Describes the automatic variables that can be used within PSRule rule definitions.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#description","title":"Description","text":"<p>PSRule lets you define rules using PowerShell blocks. A rule is defined within script files by using the <code>rule</code> keyword.</p> <p>Within a rule definition, PSRule exposes a number of automatic variables that can be read to assist with rule execution. Overwriting these variables or variable properties is not supported.</p> <p>These variables are only available while <code>Invoke-PSRule</code> is executing.</p> <p>The following variables are available for use:</p> <ul> <li>$Assert</li> <li>$Configuration</li> <li>$LocalizedData</li> <li>$PSRule</li> <li>$Rule</li> <li>$TargetObject</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#assert","title":"Assert","text":"<p>An assertion helper with methods to evaluate objects. The <code>$Assert</code> object provides a set of built-in methods and provides a consistent variable for extension.</p> <p>Each <code>$Assert</code> method returns an <code>AssertResult</code> object that contains the result of the condition.</p> <p>The following built-in assertion methods are provided:</p> <ul> <li><code>Contains</code> - The field value must contain at least one of the strings.</li> <li><code>EndsWith</code> - The field value must match at least one suffix.</li> <li><code>FileHeader</code> - The file must contain a comment header.</li> <li><code>FilePath</code> - The file path must exist.</li> <li><code>Greater</code> - The field value must be greater.</li> <li><code>GreaterOrEqual</code> - The field value must be greater or equal to.</li> <li><code>HasDefaultValue</code> - The object should not have the field or the field value is set to the default value.</li> <li><code>HasField</code> - The object must have any of the specified fields.</li> <li><code>HasFields</code> - The object must have all of the specified fields.</li> <li><code>HasFieldValue</code> - The object must have the specified field and that field is not empty.</li> <li><code>HasJsonSchema</code> - The object must reference a JSON schema with the <code>$schema</code> field.</li> <li><code>In</code> - The field value must be included in the set.</li> <li><code>IsArray</code> - The field value must be an array.</li> <li><code>IsBoolean</code> - The field value must be a boolean.</li> <li><code>IsInteger</code> - The field value must be an integer.</li> <li><code>IsLower</code> - The field value must include only lowercase characters.</li> <li><code>IsNumeric</code> - The field value must be a numeric type.</li> <li><code>IsString</code> - The field value must be a string.</li> <li><code>IsUpper</code> - The field value must include only uppercase characters.</li> <li><code>JsonSchema</code> - The object must validate successfully against a JSON schema.</li> <li><code>Less</code> - The field value must be less.</li> <li><code>LessOrEqual</code> - The field value must be less or equal to.</li> <li><code>Match</code> - The field value matches a regular expression pattern.</li> <li><code>NotIn</code> - The field value must not be included in the set.</li> <li><code>NotMatch</code> - The field value does not match a regular expression pattern.</li> <li><code>NullOrEmpty</code> - The object must not have the specified field or it must be empty.</li> <li><code>TypeOf</code> - The field value must be of the specified type.</li> <li><code>StartsWith</code> - The field value must match at least one prefix.</li> <li><code>Version</code> - The field value must be a semantic version string.</li> </ul> <p>The <code>$Assert</code> variable can only be used within a rule definition block.</p> <p>For detailed information on the assertion helper see about_PSRule_Assert.</p> <p>Syntax:</p> <pre><code>$Assert\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: Determine if $TargetObject is valid against the provided schema\nRule 'UseJsonSchema' {\n    $Assert.JsonSchema($TargetObject, 'schemas/PSRule-options.schema.json')\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#configuration","title":"Configuration","text":"<p>A dynamic object with properties names that map to configuration values set in the baseline.</p> <p>When accessing configuration:</p> <ul> <li>Configuration keys are case sensitive.</li> <li>Configuration values are read only.</li> <li>Configuration values can be accessed through helper methods.</li> </ul> <p>The following helper methods are available:</p> <ul> <li><code>GetStringValues(string configurationKey)</code> - Returns an array of strings, based on <code>configurationKey</code>.</li> </ul> <p>Syntax:</p> <pre><code>$Configuration.&lt;configurationKey&gt;\n</code></pre> <pre><code>$Configuration.GetStringValues(&lt;configurationKey&gt;)\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: This rule uses a threshold stored as $Configuration.appServiceMinInstanceCount\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n    $TargetObject.Sku.capacity -ge $Configuration.appServiceMinInstanceCount\n} -Configure @{ appServiceMinInstanceCount = 2 }\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#localizeddata","title":"LocalizedData","text":"<p>A dynamic object with properties names that map to localized data messages in a <code>.psd1</code> file.</p> <p>When using localized data, PSRule loads localized strings as a hashtable from <code>PSRule-rules.psd1</code>.</p> <p>The following logic is used to locate <code>PSRule-rules.psd1</code>:</p> <ul> <li>If the rules are loose (not part of a module), PSRule will search for <code>PSRule-rules.psd1</code> in the <code>.\\&lt;culture&gt;\\</code> subdirectory relative to where the rule script .ps1 file is located.</li> <li>When the rules are shipped as part of a module, PSRule will search for <code>PSRule-rules.psd1</code> in the <code>.\\&lt;culture&gt;\\</code> subdirectory relative to where the module manifest .psd1 file is located.</li> </ul> <p>When accessing localized data:</p> <ul> <li>Message names are case sensitive.</li> <li>Message values are read only.</li> </ul> <p>Syntax:</p> <pre><code>$LocalizedData.&lt;messageName&gt;\n</code></pre> <p>Examples:</p> <pre><code># Data for rules stored in PSRule-rules.psd1\n@{\n    WithLocalizedDataMessage = 'LocalizedMessage for en-ZZ. Format={0}.'\n}\n</code></pre> <pre><code># Synopsis: Use -f to generate a formatted localized warning\nRule 'WithLocalizedData' {\n    Write-Warning -Message ($LocalizedData.WithLocalizedDataMessage -f $TargetObject.Type)\n}\n</code></pre> <p>This rule returns a warning message similar to:</p> <pre><code>LocalizedMessage for en-ZZ. Format=TestType.\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#psrule","title":"PSRule","text":"<p>An object representing the current context during execution.</p> <p>The following properties are available for read access:</p> <ul> <li><code>Badges</code> - A helper to generate badges within PSRule.   This property can only be called within the <code>-End</code> block of a convention.</li> <li><code>Field</code> - A hashtable of custom bound fields.   See option <code>Binding.Field</code> for more information.</li> <li><code>Input</code> - Allows adding additional input paths to the pipeline.</li> <li><code>Repository</code> - Provides access to information about the current repository.</li> <li><code>Scope</code> - Any scopes assigned to the object currently being processed by the pipeline.</li> <li><code>Source</code> - A collection of sources for the object currently being processed on the pipeline.</li> <li><code>TargetObject</code> - The object currently being processed on the pipeline.</li> <li><code>TargetName</code> - The name of the object currently being processed on the pipeline.   This property will automatically default to <code>TargetName</code> or <code>Name</code> properties of the object if they exist.</li> <li><code>TargetType</code> - The type of the object currently being processed on the pipeline.   This property will automatically bind to <code>PSObject.TypeNames[0]</code> by default.</li> <li><code>Output</code> - The output of all rules.   This property can only be called within the <code>-End</code> block of a convention.</li> </ul> <p>The following properties are available for read/ write access:</p> <ul> <li><code>Data</code> - A hashtable of custom data. This property can be populated during rule or begin/ process convention execution. Custom data is not used by PSRule directly, and is intended to be used by downstream processes that need to interpret PSRule results.</li> </ul> <p>To bind fields that already exist on the target object use custom binding and <code>Binding.Field</code>. Use custom data to store data that must be calculated during rule execution.</p> <p>The following helper methods are available:</p> <ul> <li><code>GetContent(PSObject sourceObject)</code> - Returns the content of a file as one or more objects.   The parameter <code>sourceObject</code> should be a <code>InputFileInfo</code>,<code>FileInfo</code>, or <code>Uri</code> object.</li> <li><code>GetContentField(PSObject sourceObject, string field)</code> - Returns the content of a file as one or more objects.   The parameter <code>sourceObject</code> should be a <code>InputFileInfo</code>,<code>FileInfo</code>, or <code>Uri</code> object.   The parameter <code>field</code> is an field within each object to return.   If the field does not exist on the object, an object is not returned.</li> <li><code>GetContentFirstOrDefault(PSObject sourceObject)</code> - Returns the content of a file as on object.   The parameter <code>sourceObject</code> should be a <code>InputFileInfo</code>,<code>FileInfo</code>, or <code>Uri</code> object.   If more than one object is contained in the file, only the first object is returned.   When the source file contains no objects null is returned.</li> <li><code>Import(PSObject[] sourceObject)</code> - Imports one or more source objects into the pipeline.   This method can only be called within the <code>-Initialize</code> or <code>-Begin</code> block of a convention.   Use this method to expand an object into child objects that will be processed independently.   Objects imported using this method will be excluded from the <code>Input.ObjectPath</code> option if set.</li> <li><code>ImportWithType(string type, PSObject[] sourceObject)</code> - Imports one or more source objects into the pipeline.   This method can only be called within the <code>-Initialize</code> or <code>-Begin</code> block of a convention.   Use this method to expand an object into child objects that will be processed independently.   Objects imported using this method will be excluded from the <code>Input.ObjectPath</code> option if set.   When <code>Binding.PreferTargetInfo</code> is true, the type will be automatically used as the <code>TargetType</code> for the imported object.</li> <li><code>AddService(string id, object service)</code> - Add a service to the current context.   The service can be retrieved using <code>$PSRule.GetService(id)</code>.   The service object will be available to all rules and cleaned up after all rules are executed.   Services should implement the <code>IDisposable</code> interface to perform additional cleanup.   This method can only be called within the <code>-Initialize</code> block of a convention.</li> <li><code>GetService(string id)</code> - Retrieves a service previously added by a convention.</li> <li><code>GetPath(object sourceObject, string path)</code> - Evalute an object path expression and returns the resulting objects.</li> </ul> <p>The file format is detected based on the same file formats as the option <code>Input.Format</code>. i.e. Yaml, Json, Markdown, and PowerShell Data.</p> <p>Syntax:</p> <pre><code>$PSRule\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: This rule determines if the target object matches the naming convention\nRule 'NamingConvention' {\n    $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\n</code></pre> <pre><code># Synopsis: Use allowed environment tags\nRule 'CustomData' {\n    Recommend 'Environment must be set to an allowed value'\n    Within 'Tags.environment' 'production', 'test', 'development'\n\n    if ($TargetObject.Tags.environment -in 'prod') {\n        $PSRule.Data['targetEnvironment'] = 'production'\n    }\n    elseif ($TargetObject.Tags.environment -in 'dev', 'develop') {\n        $PSRule.Data['targetEnvironment'] = 'development'\n    }\n    elseif ($TargetObject.Tags.environment -in 'tst', 'testing') {\n        $PSRule.Data['targetEnvironment'] = 'test'\n    }\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#rule","title":"Rule","text":"<p>An object representing the current rule during execution.</p> <p>The following properties are available for read access:</p> <ul> <li><code>RuleName</code> - The name of the rule.</li> <li><code>RuleId</code> - A unique identifier for the rule.</li> </ul> <p>Syntax:</p> <pre><code>$Rule\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: This rule determines if the target object matches the naming convention\nRule 'resource.NamingConvention' {\n    $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#targetobject","title":"TargetObject","text":"<p>The value of the pipeline object currently being processed. <code>$TargetObject</code> is set by using the <code>-InputObject</code> parameter of <code>Invoke-PSRule</code>.</p> <p>When more than one input object is set, each object will be processed sequentially.</p> <p>Syntax:</p> <pre><code>$TargetObject\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: Check that sku capacity is set to at least 2\nRule 'HasMinInstances' {\n    $TargetObject.Sku.capacity -ge 2\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/cli/","title":"PSRule CLI","text":"<p>Abstract</p> <p>PSRule provides a command-line interface (CLI) to run rules and analyze results. This article describes the commands available in the CLI.</p> <p>For details on installing the PSRule CLI, see Install PSRule.</p>"},{"location":"concepts/cli/#commands","title":"Commands","text":"<p>The following commands are available in the CLI:</p> <ul> <li>run \u2014 Run rules against an input path and output the results.</li> <li>module \u2014 Manage or restore modules tracked by the module lock file and configured options.</li> </ul>"},{"location":"concepts/cli/#-version","title":"<code>--version</code>","text":"<p>Show the version information for PSRule.</p> <p>For example:</p> <pre><code>ps-rule --version\n</code></pre>"},{"location":"concepts/cli/#global-options","title":"Global options","text":"<p>The following global options can be used with any command:</p>"},{"location":"concepts/cli/#-option","title":"<code>--option</code>","text":"<p>Specifies the path to an options file. By default, the CLI will look for a file named <code>ps-rule.yaml</code> in the current directory.</p>"},{"location":"concepts/cli/#-h-help","title":"<code>-?</code> | <code>-h</code> | <code>--help</code>","text":"<p>Display help and usage information for the PSRule CLI and commands. To display help for a specific command, use <code>--help</code> with the command name.</p> <p>For example:</p> <pre><code>ps-rule run --help\n</code></pre>"},{"location":"concepts/cli/#-verbose","title":"<code>--verbose</code>","text":"<p>Display verbose output for the selected command.</p>"},{"location":"concepts/cli/#-debug","title":"<code>--debug</code>","text":"<p>Display debug output for the selected command.</p>"},{"location":"concepts/cli/module/","title":"ps-rule module","text":"<p>Abstract</p> <p>Use the <code>module</code> command to manage or restore modules tracked by the module lock file and configured options. (<code>ps-rule.lock.json</code>). The module lock file, provides consistent module versions across multiple machines and environments. For more information, see Lock file.</p>"},{"location":"concepts/cli/module/#usage","title":"Usage","text":"PSRule CLI command-line<pre><code>ps-rule module [subcommand] [options]\n</code></pre> <p>To use the <code>module</code> command, choose one of the available subcommands:</p> <ul> <li>module init</li> <li>module list</li> <li>module add</li> <li>module remove</li> <li>module restore</li> <li>module upgrade</li> </ul>"},{"location":"concepts/cli/module/#module-init","title":"<code>module init</code>","text":"<p>Initialize a new lock file based on existing options. Using this command, the module lock file is created or updated.</p> <p>If <code>ps-rule.yaml</code> option are configured to included module (<code>Include.Modules</code>), these a automatically added to the lock file. Any required version constraints set by the <code>Requires</code> option are taken into consideration.</p> <p>Optional parameters:</p> <ul> <li><code>--force</code> - Force the creation of a new lock file, even if one already exists.</li> </ul> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module init\n</code></pre> <p>For example, force the creation of a new lock file, even if one already exists:</p> PSRule CLI command-line<pre><code>ps-rule module init --force\n</code></pre>"},{"location":"concepts/cli/module/#module-list","title":"<code>module list</code>","text":"<p>List any module and the installed versions from the lock file.</p>"},{"location":"concepts/cli/module/#module-add","title":"<code>module add</code>","text":"<p>Add one or more modules to the module lock file. If the lock file does not exist, it is created.</p> <p>By default, the latest stable version of the module is added. Any required version constraints set by the <code>Requires</code> option are taken into consideration.</p> <p>To use a specific module version, use the <code>--version</code> argument.</p> <p>Optional parameters:</p> <ul> <li><code>--version</code> - Specifies a specific version of the module to add.   By default, the latest stable version of the module is added.   Any required version constraints set by the <code>Requires</code> option are taken into consideration.</li> </ul> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module add PSRule.Rules.Azure\n</code></pre> <p>For example, a specific version of the module is added:</p> PSRule CLI command-line<pre><code>ps-rule module add PSRule.Rules.Azure --version 1.32.1\n</code></pre>"},{"location":"concepts/cli/module/#module-remove","title":"<code>module remove</code>","text":"<p>Remove one or more modules from the lock file.</p> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module remove PSRule.Rules.Azure\n</code></pre>"},{"location":"concepts/cli/module/#module-restore","title":"<code>module restore</code>","text":"<p>Restore modules from the module lock file (<code>ps-rule.lock.json</code>) and configured options.</p> <p>Optional parameters:</p> <ul> <li><code>--force</code> - Restore modules even when an existing version that meets constraints is already installed locally.</li> </ul> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module restore\n</code></pre> <p>For example, force restore of all modules:</p> PSRule CLI command-line<pre><code>ps-rule module restore --force\n</code></pre>"},{"location":"concepts/cli/module/#module-upgrade","title":"<code>module upgrade</code>","text":"<p>Upgrade to the latest versions any modules within the lock file.</p> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module upgrade\n</code></pre>"},{"location":"concepts/cli/module/#next-steps","title":"Next steps","text":"<p>For more information on the module lock file, see Lock file.</p> <p>To find out more about the commands available with the PSRule CLI, see PSRule CLI.</p>"},{"location":"concepts/cli/run/","title":"ps-rule run","text":"<p>Abstract</p> <p>Use the <code>run</code> command to run rules against an input path and output the results.</p>"},{"location":"concepts/cli/run/#usage","title":"Usage","text":"PSRule CLI command-line<pre><code>ps-rule run [options]\n</code></pre>"},{"location":"concepts/cli/run/#options","title":"Options","text":""},{"location":"concepts/cli/run/#-input-path-f","title":"<code>--input-path</code> | <code>-f</code>","text":"<p>The file or directory path to search for input file to use during a run. By default, this is the current working path.</p>"},{"location":"concepts/cli/run/#-module-m","title":"<code>--module</code> | <code>-m</code>","text":"<p>The name of one or more modules that contain rules or resources to use during a run.</p>"},{"location":"concepts/cli/run/#-baseline","title":"<code>--baseline</code>","text":"<p>The name of a specific baseline to use. Currently, only a single baseline can be used during a run.</p>"},{"location":"concepts/cli/run/#-outcome","title":"<code>--outcome</code>","text":"<p>Specifies the rule results to show in output. By default, <code>Pass</code>/ <code>Fail</code>/ <code>Error</code> results are shown.</p> <p>Allows filtering of results by outcome. The supported values are:</p> <ul> <li><code>Pass</code> - Results for rules that passed.</li> <li><code>Fail</code> - Results for rules that did not pass.</li> <li><code>Error</code> - Results for rules that raised an error are returned.</li> <li><code>Processed</code> - All results that were processed.   This aggregated outcome includes <code>Pass</code>, <code>Fail</code>, or <code>Error</code> results.</li> <li><code>Problem</code> - Processed results that did not pass.   This aggregated outcome includes <code>Fail</code>, or <code>Error</code> results.</li> </ul> <p>To specify multiple values, specify the parameter multiple times. For example: <code>--outcome Pass --Outcome Fail</code>.</p>"},{"location":"concepts/cli/run/#-output-o","title":"<code>--output</code> | <code>-o</code>","text":"<p>Specifies the format to use when outputting results.</p>"},{"location":"concepts/cli/run/#-output-path","title":"<code>--output-path</code>","text":"<p>Specifies a path to write results to.</p>"},{"location":"concepts/cli/run/#next-steps","title":"Next steps","text":"<p>To find out more about the commands available with the PSRule CLI, see PSRule CLI.</p>"},{"location":"expressions/functions/","title":"Functions","text":"<p>Abstract</p> <p>Functions are an advanced language feature specific to YAML and JSON expressions. That extend the language to allow for more complex use cases with expressions. Functions don't apply to script expressions because PowerShell already has rich support for complex manipulation.</p> <p>Experimental</p> <p>Functions are a work in progress and subject to change. We hope to add more functions, broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.</p> <p>Functions cover two (2) main scenarios:</p> <ul> <li>Transformation \u2014 you need to perform minor transformation before a condition.</li> <li>Configuration \u2014 you want to configure an input into a condition.</li> </ul>"},{"location":"expressions/functions/#using-functions","title":"Using functions","text":"<p>It may be necessary to perform minor transformation before evaluating a condition.</p> <ul> <li><code>boolean</code> - Convert a value to a boolean.</li> <li><code>concat</code> - Concatenate multiple values.</li> <li><code>configuration</code> - Get a configuration value.</li> <li><code>first</code> - Return the first element in an array or the first character of a string.</li> <li><code>integer</code> - Convert a value to an integer.</li> <li><code>last</code> - Return the last element in an array or the last character of a string.</li> <li><code>padLeft</code> - Pad a value with a character on the left to meet the specified length.</li> <li><code>padRight</code> - Pad a value with a character on the right to meet the specified length.</li> <li><code>path</code> - Get a value from an object path.</li> <li><code>replace</code> - Replace an old string with a new string.</li> <li><code>split</code> - Split a string into an array by a delimiter.</li> <li><code>string</code> - Convert a value to a string.</li> <li><code>substring</code> - Extract a substring from a string.</li> <li><code>trim</code> - Remove whitespace from the start and end of a string.</li> </ul>"},{"location":"expressions/functions/#supported-conditions","title":"Supported conditions","text":"<p>Currently functions are only supported on a subset of conditions. The conditions that are supported are:</p> <ul> <li><code>equals</code></li> <li><code>notEquals</code></li> <li><code>count</code></li> <li><code>less</code></li> <li><code>lessOrEquals</code></li> <li><code>greater</code></li> <li><code>greaterOrEquals</code></li> </ul>"},{"location":"expressions/functions/#examples","title":"Examples","text":"YAML<pre><code>---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example1\nspec:\n  if:\n    value:\n      $:\n        substring:\n          path: name\n        length: 7\n    equals: TestObj\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example2\nspec:\n  if:\n    value:\n      $:\n        configuration: 'ConfigArray'\n    count: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example3\nspec:\n  if:\n    value:\n      $:\n        boolean: true\n    equals: true\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example4\nspec:\n  if:\n    value:\n      $:\n        concat:\n        - path: name\n        - string: '-'\n        - path: name\n    equals: TestObject1-TestObject1\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example5\nspec:\n  if:\n    value:\n      $:\n        integer: 6\n    greater: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example6\nspec:\n  if:\n    value: TestObject1-TestObject1\n    equals:\n      $:\n        concat:\n        - path: name\n        - string: '-'\n        - path: name\n</code></pre>"},{"location":"expressions/functions/#recommended-content","title":"Recommended content","text":"<ul> <li>Create a standalone rule</li> <li>Expressions</li> <li>Sub-selectors</li> </ul>"},{"location":"expressions/sub-selectors/","title":"Sub-selectors","text":"<p>Abstract</p> <p>This topic covers sub-selectors which are a PSRule language feature specific to YAML and JSON expressions. They are useful for filtering out objects that you do not want to evaluate. Sub-selectors don't apply to script expressions because PowerShell already has rich support for filtering.</p> <p>Experimental</p> <p>Sub-selectors are a work in progress and subject to change. We hope to add broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.</p> <p>Sub-selectors cover two (2) main scenarios:</p> <ul> <li>Pre-conditions \u2014 you want to filtering out objects before a rule is run.</li> <li>Object filtering \u2014 you want to limit a condition to specific elements in a list of items.</li> </ul>"},{"location":"expressions/sub-selectors/#pre-conditions","title":"Pre-conditions","text":"<p>PSRule can process many different types of objects. Rules however, are normally written to test a specific property or type of object. So it is important that rules only run on objects that you want to evaluate. Pre-condition sub-selectors are one way you can determine if a rule should be run.</p> <p>To use a sub-selector as a pre-condition, use the <code>where</code> property, directly under the <code>spec</code>. The expressions in the sub-selector follow the same form that you can use in rules.</p> <p>For example:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector precondition.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.Precondition\nspec:\n  where:\n    field: 'kind'\n    equals: 'api'\n  condition:\n    field: resources\n    count: 10\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector precondition.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.Precondition\"\n  },\n  \"spec\": {\n    \"where\": {\n      \"field\": \"kind\",\n      \"equals\": \"api\"\n    },\n    \"condition\": {\n      \"field\": \"resources\",\n      \"count\": 10\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ol> <li>The <code>where</code> property is the start of a sub-selector.</li> <li>The sub-selector checks if the <code>kind</code> property equals <code>api</code>.</li> </ol> <p>The rule does not run if the:</p> <ul> <li>The object does not have a <code>kind</code> property. OR</li> <li>The value of the <code>kind</code> property is not <code>api</code>.</li> </ul> <p>Tip</p> <p>Other types of pre-conditions also exist that allow you to filter based on type or by a shared selector.</p>"},{"location":"expressions/sub-selectors/#object-filter","title":"Object filter","text":"<p>When you are evaluating an object, you can use sub-selectors to limit the condition. This is helpful when dealing with properties that are a list of items. Properties that contain a list of items may contain a sub-set of items that you want to evaluate.</p> <p>For example, the object may look like this:</p> YAMLJSON <pre><code>name: app1\ntype: Microsoft.Web/sites\nresources:\n- name: web\n  type: Microsoft.Web/sites/config\n  properties:\n    detailedErrorLoggingEnabled: true\n</code></pre> <pre><code>{\n  \"name\": \"app1\",\n  \"type\": \"Microsoft.Web/sites\",\n  \"resources\": [\n    {\n      \"name\": \"web\",\n      \"type\": \"Microsoft.Web/sites/config\",\n      \"properties\": {\n        \"detailedErrorLoggingEnabled\": true\n      }\n    }\n  ]\n}\n</code></pre> <p>A rule to test if any sub-resources with the <code>detailedErrorLoggingEnabled</code> set to <code>true</code> exist might look like this:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.Filter\nspec:\n  condition:\n    field: resources\n    where:\n      type: '.'\n      equals: 'Microsoft.Web/sites/config'\n    allOf:\n    - field: properties.detailedErrorLoggingEnabled\n      equals: true\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector filter.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.Filter\"\n  },\n  \"spec\": {\n    \"condition\": {\n      \"field\": \"resources\",\n      \"where\": {\n        \"type\": \".\",\n        \"equals\": \"Microsoft.Web/sites/config\"\n      },\n      \"allOf\": [\n        {\n          \"field\": \"properties.detailedErrorLoggingEnabled\",\n          \"equals\": true\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ul> <li>If the array property <code>resources</code> exists, any items with a type of <code>Microsoft.Web/sites/config</code> are evaluated.<ul> <li>Each item must have the <code>properties.detailedErrorLoggingEnabled</code> property set to <code>true</code> to pass.</li> <li>Items without the <code>properties.detailedErrorLoggingEnabled</code> property fail.</li> <li>Items with the <code>properties.detailedErrorLoggingEnabled</code> property set to a value other then <code>true</code> fail.</li> </ul> </li> <li>If the <code>resources</code> property does not exist, the rule fails.</li> <li>If the <code>resources</code> property exists but has 0 items of type <code>Microsoft.Web/sites/config</code>, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> but any fail, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> and all pass, the rule passes.</li> </ul>"},{"location":"expressions/sub-selectors/#when-there-are-no-results","title":"When there are no results","text":"<p>Given the example, is important to understand what happens by default if:</p> <ul> <li>The <code>resources</code> property doesn't exist. OR</li> <li>The <code>resources</code> property doesn't contain any items that match the sub-selector condition.</li> </ul> <p>In either of these two cases, the sub-selector will return <code>false</code> and fail the rule. The rule fails because there is no secondary conditions that could be used instead.</p> <p>If this was not the desired behavior, you could:</p> <ul> <li>Use a pre-condition to avoid running the rule.</li> <li>Group the sub-selector into a <code>anyOf</code>, and provide a secondary condition.</li> <li>Use a quantifier to determine how many items must match sub-selector and match the <code>allOf</code> / <code>anyOf</code> operator.</li> </ul> <p>For example:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.FilterOr\nspec:\n  condition:\n    anyOf:\n\n    - field: resources\n      where:\n        type: '.'\n        equals: 'Microsoft.Web/sites/config'\n      allOf:\n      - field: properties.detailedErrorLoggingEnabled\n        equals: true\n\n    - field: resources\n      exists: false\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector filter.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.FilterOr\"\n  },\n  \"spec\": {\n    \"condition\": {\n      \"anyOf\": [\n        {\n          \"field\": \"resources\",\n          \"where\": {\n            \"type\": \".\",\n            \"equals\": \"Microsoft.Web/sites/config\"\n          },\n          \"allOf\": [\n            {\n              \"field\": \"properties.detailedErrorLoggingEnabled\",\n              \"equals\": true\n            }\n          ]\n        },\n        {\n          \"field\": \"resources\",\n          \"exists\": false\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ul> <li>If the array property <code>resources</code> exists, any items with a type of <code>Microsoft.Web/sites/config</code> are evaluated.<ul> <li>Each item must have the <code>properties.detailedErrorLoggingEnabled</code> property set to <code>true</code> to pass.</li> <li>Items without the <code>properties.detailedErrorLoggingEnabled</code> property fail.</li> <li>Items with the <code>properties.detailedErrorLoggingEnabled</code> property set to a value other then <code>true</code> fail.</li> </ul> </li> <li>If the <code>resources</code> property does not exist, the rule passes.</li> <li>If the <code>resources</code> property exists but has 0 items of type <code>Microsoft.Web/sites/config</code>, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> but any fail, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> and all pass, the rule passes.</li> </ul>"},{"location":"expressions/sub-selectors/#using-a-quantifier-with-sub-selectors","title":"Using a quantifier with sub-selectors","text":"<p>When iterating over a list of items, you may want to determine how many items must match. A quantifier determines how many items in the list match. Matching items must be:</p> <ul> <li>Selected by the sub-selector.</li> <li>Match the condition of the operator.</li> </ul> <p>Supported quantifiers are:</p> <ul> <li><code>count</code> \u2014 The number of items must equal then the specified value.</li> <li><code>less</code> \u2014 The number of items must less then the specified value.</li> <li><code>lessOrEqual</code> \u2014 The number of items must less or equal to the specified value.</li> <li><code>greater</code> \u2014 The number of items must greater then the specified value.</li> <li><code>greaterOrEqual</code> \u2014 The number of items must greater or equal to the specified value.</li> </ul> <p>For example:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector quantifier.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.Quantifier\nspec:\n  condition:\n    field: resources\n    where:\n      type: '.'\n      equals: 'Microsoft.Web/sites/config'\n    greaterOrEqual: 1\n    allOf:\n    - field: properties.detailedErrorLoggingEnabled\n      equals: true\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector quantifier.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.Quantifier\"\n  },\n  \"spec\": {\n    \"condition\": {\n      \"field\": \"resources\",\n      \"where\": {\n        \"type\": \".\",\n        \"equals\": \"Microsoft.Web/sites/config\"\n      },\n      \"greaterOrEqual\": 1,\n      \"allOf\": [\n        {\n          \"field\": \"properties.detailedErrorLoggingEnabled\",\n          \"equals\": true\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ul> <li>If the array property <code>resources</code> exists, any items with a type of <code>Microsoft.Web/sites/config</code> are evaluated.<ul> <li>Each item must have the <code>properties.detailedErrorLoggingEnabled</code> property set to <code>true</code> to pass.</li> <li>The number of items that pass must be greater or equal to <code>1</code>.</li> </ul> </li> <li>If the <code>resources</code> property does not exist or is empty, the number of items is <code>0</code> which fails greater or equal to <code>1</code>.</li> </ul>"},{"location":"expressions/sub-selectors/#recommended-content","title":"Recommended content","text":"<ul> <li>Create a standalone rule</li> <li>Functions</li> <li>Expressions</li> </ul>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/","title":"Keywords","text":"<p>Describes the language keywords that can be used within PSRule rule definitions.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#description","title":"Description","text":"<p>PSRule lets you define rules using PowerShell blocks. To define a rule use the <code>Rule</code> keyword.</p> <ul> <li>Rule - Creates a rule definition.</li> </ul> <p>The following are the built-in keywords that can be used within a rule definition:</p> <ul> <li>AnyOf - Assert that any of the child expressions must be true.</li> <li>AllOf - Assert that all of the child expressions must be true.</li> <li>Exists - Assert that a field or property must exist.</li> <li>Match - Assert that the field must match any of the regular expressions.</li> <li>Reason - Return a reason for why the rule failed.</li> <li>Recommend - Return a recommendation to resolve the issue and pass the rule.</li> <li>TypeOf - Assert that the object must be of a specific type.</li> <li>Within - Assert that the field must match any of the values.</li> </ul> <p>A subset of built-in keywords can be used within script preconditions:</p> <ul> <li>Exists - Assert that a field or property must exist.</li> <li>Match - Assert that the field must match any of the regular expressions.</li> <li>TypeOf - Assert that the object must be of a specific type.</li> <li>Within - Assert that the field must match any of the values.</li> </ul>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#rule","title":"Rule","text":"<p>A <code>Rule</code> definition describes an individual business rule that will be executed against each input object. Input objects can be passed on the PowerShell pipeline or supplied from file.</p> <p>To define a Rule use the <code>Rule</code> keyword followed by a name and a pair of squiggly brackets <code>{</code>. Within the <code>{ }</code> one or more conditions can be used.</p> <p>Conditions determine if the input object either Pass or Fail the rule.</p> <p>Syntax:</p> <pre><code>Rule [-Name] &lt;string&gt; [-Ref &lt;string&gt;] [-Alias &lt;string[]&gt;] [-Tag &lt;hashtable&gt;] [-When &lt;string[]&gt;] [-Type &lt;string[]&gt;] [-If &lt;scriptBlock&gt;] [-DependsOn &lt;string[]&gt;] [-Configure &lt;hashtable&gt;] [-ErrorAction &lt;ActionPreference&gt;] [-Body] {\n    ...\n}\n</code></pre> <ul> <li><code>Name</code> - The name of the rule definition. Each rule name must be unique. When packaging rules within a module, rule names must only be unique within the module.</li> <li><code>Ref</code> - An optional stable and opaque identifier that can be used to reference the rule.</li> <li><code>Alias</code> - A list of alternative names that can be used to reference the rule.</li> <li><code>Tag</code> - A hashtable of key/ value metadata that can be used to filter and identify rules and rule results.</li> <li><code>When</code> - A selector precondition that must evaluate true before the rule is executed.</li> <li><code>Type</code> - A type precondition that must match the TargetType of the pipeline object before the rule is executed.</li> <li><code>If</code> - A script precondition that must evaluate to <code>$True</code> before the rule is executed.</li> <li><code>DependsOn</code> - A list of rules this rule depends on. Rule dependencies must execute successfully before this rule is executed.</li> <li><code>Configure</code> - A set of default configuration values. These values are only used when the baseline configuration does not contain the key.</li> <li><code>ErrorAction</code> - The action to take when an error occur. Only a subset of preferences are supported, either <code>Stop</code> or <code>Ignore</code>. When <code>-ErrorAction</code> is not specified the default preference is <code>Stop</code>. When errors are ignored a rule will pass or fail based on the rule condition. Uncaught exceptions will still cause rule return an error outcome.</li> <li><code>Body</code> - A script block that specifies one or more conditions that are required for the rule to Pass.</li> </ul> <p>A condition is any valid PowerShell that return either <code>$True</code> or <code>$False</code>. Optionally, PSRule keywords can be used to help build out conditions quickly. When a rule contains more then one condition, all must return <code>$True</code> for the rule to Pass. If any one condition returns <code>$False</code> the rule has failed.</p> <p>The following restrictions apply:</p> <ul> <li>Rule conditions should only return <code>$True</code> or <code>$False</code>. Other objects should be caught with <code>Out-Null</code> or null assigned like <code>$Null = SomeCommand</code>.</li> <li>The <code>Rule</code> keyword can not be nested in a <code>Rule</code> definition.</li> <li>Variables and functions defined within <code>.Rule.ps1</code> files, but outside the <code>Rule</code> definition block are not accessible unless the <code>Global</code> scope is applied.</li> <li>Functions and variables within the caller's scope (the scope calling <code>Invoke-PSRule</code>, <code>Get-PSRule</code>, <code>Test-PSRuleTarget</code>) are not accessible.</li> <li>Cmdlets that require user interaction are not supported, i.e. <code>Read-Host</code>.</li> <li>Script preconditions can contain <code>Exists</code>, <code>Match</code>, <code>TypeOf</code> and <code>Within</code> keywords.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: This rule checks for the presence of a name field\nRule 'NameMustExist' {\n    Exists 'Name'\n}\n</code></pre> <pre><code># Synopsis: This rule checks that the title field is valid, when the rule NameMustExist is successful\nRule 'TitleIsValid' -DependsOn 'NameMustExist' {\n    Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n</code></pre> <pre><code># Synopsis: This rule uses a threshold stored as $Configuration.minInstanceCount\nRule 'HasMinInstances' {\n    $TargetObject.Sku.capacity -ge $Configuration.minInstanceCount\n} -Configure @{ minInstanceCount = 2 }\n</code></pre> <pre><code># Synopsis: This rule still passes because errors are ignored\nRule 'WithRuleErrorActionIgnore' -ErrorAction Ignore {\n    Write-Error 'Some error';\n    $True;\n}\n</code></pre>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#exists","title":"Exists","text":"<p>The <code>Exists</code> assertion is used within a <code>Rule</code> definition to assert that a field or property must exist on the pipeline object.</p> <p>Syntax:</p> <pre><code>Exists [-Field] &lt;string[]&gt; [-CaseSensitive] [-Not] [-All] [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>Field</code> - One or more fields/ properties that must exist on the pipeline object.</li> <li><code>CaseSensitive</code> - The field name must match exact case.</li> <li><code>Not</code> - Instead of checking if the field names exists they should not exist.</li> <li><code>All</code> - All fields must exist on the pipeline object, instead of only one.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Checks for the presence of a name property\nRule 'nameMustExist' {\n    Exists 'Name'\n}\n</code></pre> <pre><code># Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n    Exists 'metadata.name'\n}\n</code></pre> <pre><code># Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n    $TargetObject.metadata | Exists 'name'\n}\n</code></pre> <pre><code># Synopsis: Checks that the NotName property does not exist\nRule 'NotNameMustNotExist' {\n    Exists -Not 'NotName'\n}\n</code></pre> <pre><code># Synopsis: Checks one of Name or AlternativeName properties exist\nRule 'EitherMustExist' {\n    Exists 'Name', 'AlternativeName'\n}\n</code></pre> <pre><code># Synopsis: Checks that both Name and Type properties exist\nRule 'AllMustExist' {\n    Exists 'Name', 'Type' -All\n}\n</code></pre> <p>Output:</p> <p>If any the specified fields exists then <code>Exists</code> will return <code>$True</code>, otherwise <code>$False</code>.</p> <p>If <code>-Not</code> is used, then if any of the fields exist then <code>Exists</code> will return <code>$False</code> otherwise <code>$True</code>.</p> <p>If <code>-All</code> is used, then then all of the fields must exist, or not with the <code>-Not</code> switch. If all fields exist then <code>Exists</code> will return <code>$True</code>, otherwise <code>$False</code>. If <code>-Not</code> is used with <code>-All</code>, if all of the fields exist <code>Exists</code> will return <code>$False</code> otherwise <code>$True</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#match","title":"Match","text":"<p>The <code>Match</code> assertion is used within a <code>Rule</code> definition to assert that the value of a field or property from pipeline data must match one or more regular expressions. To optionally perform a case sensitive match use the <code>-CaseSensitive</code> switch, otherwise a case insensitive match will be used.</p> <p>Syntax:</p> <pre><code>Match [-Field] &lt;string&gt; [-Expression] &lt;string[]&gt; [-CaseSensitive] [-Not] [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>Field</code> - The name of the field that will be evaluated on the pipeline object.</li> <li><code>Expression</code> - One or more regular expressions that will be used to match the value of the field.</li> <li><code>CaseSensitive</code> - The field value must match exact case.</li> <li><code>Not</code> - Instead of checking the field value matches, the field value must not match any of the expressions.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Check that PhoneNumber is complete and formatted correctly\nRule 'validatePhoneNumber' {\n    Match 'PhoneNumber' '^(\\+61|0)([0-9] {0,1}){8}[0-9]$'\n}\n</code></pre> <p>Output:</p> <p>If any of the specified regular expressions match the field value then <code>Match</code> returns <code>$True</code>, otherwise <code>$False</code>.</p> <p>When <code>-Not</code> is used, if any of the regular expressions match the field value with <code>Match</code> return <code>$False</code>, otherwise <code>$True</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#within","title":"Within","text":"<p>The <code>Within</code> assertion is used within a <code>Rule</code> definition to assert that the value of a field or property from pipeline data must equal an item from a supplied list of allowed values. To optionally perform a case sensitive match use the <code>-CaseSensitive</code> switch, otherwise a case insensitive match will be used.</p> <p>Syntax:</p> <pre><code>Within [-Field] &lt;string&gt; [-Not] [-Like] [-Value] &lt;PSObject[]&gt; [-CaseSensitive] [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>Field</code> - The name of the field that will be evaluated on the pipeline object.</li> <li><code>Value</code> - A list of values that the field value must match.</li> <li><code>CaseSensitive</code> - The field value must match exact case. Only applies when the field value and allowed values are strings.</li> <li><code>Not</code> - Instead of checking the field value matches, the field value must not match any of the supplied values.</li> <li><code>Like</code> - Instead of using an exact match, a wildcard match is used. This switch can only be used when <code>Value</code> a string type.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n    Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n</code></pre> <pre><code># Synopsis: Ensure that the title field is not one of the specified values\nRule 'validateTitle' {\n    Within 'Title' -Not 'Mr', 'Sir'\n}\n</code></pre> <pre><code># Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n    Within 'Title' -Like 'Mr', 'M*s'\n}\n</code></pre> <p>Output:</p> <p>If any of the values match the field value then <code>Within</code> returns <code>$True</code>, otherwise <code>$False</code>.</p> <p>When <code>-Not</code> is used, if any of the values match the field value with <code>Within</code> return <code>$False</code>, otherwise <code>$True</code>.</p> <p>When <code>-Like</code> is used, the field value is matched against one or more wildcard expressions.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#allof","title":"AllOf","text":"<p>The <code>AllOf</code> assertion is used within a <code>Rule</code> definition to aggregate the result of assertions within a pair of squiggly brackets <code>{ }</code>. <code>AllOf</code> is functionally equivalent to a binary and, where when all of the contained assertions return <code>$True</code>, <code>AllOf</code> will return <code>$True</code>.</p> <p>Syntax:</p> <pre><code>AllOf [-Body] {\n    &lt;assertion&gt;\n    [&lt;assertion&gt;]\n    ...\n}\n</code></pre> <ul> <li><code>Body</code> - A script block definition of the containing one or more PSRule keywords and PowerShell expressions.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: The Name field must exist and have a value of either John or Jane\nRule 'nameCheck' {\n    AllOf {\n        Exists 'Name'\n        Within 'Name' 'John', 'Jane'\n    }\n}\n</code></pre> <p>Output:</p> <p>If all of the assertions return <code>$True</code> AllOf will return <code>$True</code>, otherwise <code>$False</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#anyof","title":"AnyOf","text":"<p>The <code>AnyOf</code> assertion is used within a <code>Rule</code> definition to aggregate the result of assertions within a pair of squiggly brackets <code>{ }</code>. <code>AnyOf</code> is functionally equivalent to a binary or, where if any of the contained assertions returns <code>$True</code>, <code>AnyOf</code> will return <code>$True</code>.</p> <p>Syntax:</p> <pre><code>AnyOf [-Body] {\n    &lt;assertion&gt;\n    [&lt;assertion&gt;]\n    ...\n}\n</code></pre> <ul> <li><code>Body</code> - A script block definition of the containing one or more PSRule keywords and PowerShell expressions.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: The Last or Surname field must exist\nRule 'personCheck' {\n    AnyOf {\n        Exists 'Last'\n        Exists 'Surname'\n    }\n}\n</code></pre> <p>Output:</p> <p>If any of the assertions return <code>$True</code> AnyOf will return <code>$True</code>, otherwise <code>$False</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#typeof","title":"TypeOf","text":"<p>The <code>TypeOf</code> assertion is used within a <code>Rule</code> definition to evaluate if the pipeline object matches one or more of the supplied type names.</p> <p>Syntax:</p> <pre><code>TypeOf [-TypeName] &lt;string[]&gt; [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>TypeName</code> - One or more type names which will be evaluated against the pipeline object. <code>TypeName</code> is case sensitive.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: The object must be a hashtable\nRule 'objectType' {\n    TypeOf 'System.Collections.Hashtable'\n}\n</code></pre> <p>Output:</p> <p>If any the specified type names match the pipeline object then TypeOf will return <code>$True</code>, otherwise <code>$False</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#reason","title":"Reason","text":"<p>The <code>Reason</code> keyword is used within a <code>Rule</code> definition to provide a message that indicates the reason the rule failed. The reason is included in detailed results.</p> <p>A reason is only included when the rule fails or errors. The outcomes <code>Pass</code> and <code>None</code> do not include reason.</p> <p>Use this keyword when you want to implement custom logic. Built-in keywords including <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> automatically include a reason when they fail.</p> <p>Syntax:</p> <pre><code>Reason [-Text] &lt;string&gt;\n</code></pre> <ul> <li><code>Text</code> - A message that includes the reason for the failure.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Provide reason the rule failed\nRule 'objectRecommend' {\n    Reason 'A minimum of two (2) instances are required'\n    $TargetObject.count -ge 2\n}\n</code></pre> <p>Output:</p> <p>None.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#recommend","title":"Recommend","text":"<p>The <code>Recommend</code> keyword is used within a <code>Rule</code> definition to provide a recommendation to resolve the issue and pass the rule. This may include manual steps to change that state of the object or the desired state accessed by the rule.</p> <p>The recommendation can only be set once per rule. Each object will use the same recommendation.</p> <p>Syntax:</p> <pre><code>Recommend [-Text] &lt;string&gt;\n</code></pre> <ul> <li><code>Text</code> - A message that includes the process to resolve the issue and pass the rule.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Provide recommendation to resolve the issue\nRule 'objectRecommend' {\n    Recommend 'Use at least two (2) instances'\n    $TargetObject.count -ge 2\n}\n</code></pre> <p>Output:</p> <p>None.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#examples","title":"Examples","text":"<pre><code># Synopsis: App Service Plan has multiple instances\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n    Recommend 'Use at least two (2) instances'\n\n    $TargetObject.Sku.capacity -ge 2\n}\n</code></pre>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#links","title":"Links","text":"<ul> <li>[Invoke-PSRule]</li> </ul>"},{"location":"quickstart/standalone-rule/","title":"Create a standalone rule","text":"<p>You can use PSRule to create tests for PowerShell objects piped to PSRule for validation. Each test is called a rule.</p> <p>PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.</p> <p>Abstract</p> <p>This topic covers how to create a rule using YAML, JSON, and PowerShell by example. In this quickstart, will be using native PowerShell objects. For an example of reading objects from disk, continue reading Testing infrastructure.</p>"},{"location":"quickstart/standalone-rule/#prerequisites","title":"Prerequisites","text":"<p>For this quickstart, PSRule must be installed locally on MacOS, Linux, or Windows. To install PSRule locally, open PowerShell and run the following <code>Install-Module</code> command. If you don't have PowerShell installed, complete Installing PowerShell first.</p> PowerShell<pre><code>Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\n</code></pre> <p>Tip</p> <p>PowerShell is installed by default on Windows. If these instructions don't work for you, your administrator may have restricted how PowerShell can be used in your environment. You or your administrator may be able to install PSRule for all users as a local administrator. See Getting the modules for instructions on how to do this.</p> <p>Tip</p> <p>To make you editing experience even better, consider installing the Visual Studio Code extension.</p>"},{"location":"quickstart/standalone-rule/#scenario-test-for-image-files","title":"Scenario - Test for image files","text":"<p>In our quickstart scenario, we have been tasked with creating a rule to test for image files. When a file ending with the <code>.jpg</code> or <code>.png</code> extension is found the rule should fail.</p> <p>We will be using the following PowerShell code to get a list of files.</p> PowerShell<pre><code>$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\n</code></pre> <p>Info</p> <p>The path to search <code>$Env:HOME</code> defaults to the current user's home directory. This directory is used so this quickstart works on Windows and Linux operating systems. Feel free to update this path to a more suitable directory on your local machine.</p>"},{"location":"quickstart/standalone-rule/#define-the-file-type-rule","title":"Define the file type rule","text":"<p>Before an object can be tested with PSRule, one or more rules must be defined. Each rule is defined in a file named with the suffix <code>.Rule.yaml</code>, <code>.Rule.jsonc</code>, or <code>.Rule.ps1</code>. Multiple rules can be defined in a single file.</p> <p>A rule that fail on files with <code>.jpg</code> or <code>.png</code> extensions is shown in YAML, JSON, and PowerShell formats. You only need to choose one format, however you can choose to create all three to try out each format.</p> YAMLJSONPowerShell <p>Create the <code>FileType.Rule.yaml</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>FileType.Rule.yaml</code>.</p> YAML<pre><code>---\n# Synopsis: Image files are not permitted.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.FileType\nspec:\n  type:\n  - System.IO.FileInfo\n  condition:\n    field: Extension\n    notIn:\n    - .jpg\n    - .png\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Yaml.FileType</code>.</li> <li>The <code>type</code> property ensures the rule will only run for file info objects.     Other objects that might be piped to PSRule will be skipped by the <code>Yaml.FileType</code> rule.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each file returned with <code>Get-ChildItem</code>.     Specifically, the <code>Extension</code> property of each <code>FileInfo</code> object will be compared.     The value of <code>Extension</code> should not be either <code>.jpg</code> or <code>.png</code>.</li> </ol> <p>Create the <code>FileType.Rule.jsonc</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>FileType.Rule.jsonc</code>.</p> JSON<pre><code>[\n    {\n        // Synopsis: Image files are not permitted.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Json.FileType\"\n        },\n        \"spec\": {\n            \"type\": [\n                \"System.IO.FileInfo\"\n            ],\n            \"condition\": {\n                \"field\": \"Extension\",\n                \"notIn\": [\n                    \".jpg\",\n                    \".png\"\n                ]\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Json.FileType</code>.</li> <li>The <code>type</code> property ensures the rule will only run for file info objects.     Other objects that might be piped to PSRule will be skipped by the <code>Json.FileType</code> rule.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each file returned with <code>Get-ChildItem</code>.     Specifically, the <code>Extension</code> property of each <code>FileInfo</code> object will be compared.     The value of <code>Extension</code> should not be either <code>.jpg</code> or <code>.png</code>.</li> </ol> <p>Create the <code>FileType.Rule.ps1</code> file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you save <code>FileType.Rule.ps1</code>.</p> PowerShell<pre><code># Synopsis: Image files are not permitted.\nRule 'PS.FileType' -Type 'System.IO.FileInfo' {\n    $Assert.NotIn($TargetObject, 'Extension', @('.jpg', '.png'))\n}\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>PS.FileType</code>.</li> <li>The <code>-Type</code> parameter ensures the rule will only run for file info objects.     Other objects that might be piped to PSRule will be skipped by the <code>PS.FileType</code> rule.</li> <li>The condition contained within the curly braces <code>{ }</code> determines the checks PSRule will use to test each file returned with <code>Get-ChildItem</code>.</li> <li>The <code>$Assert.NotIn</code> method checks the <code>Extension</code> property is not set to <code>.jpg</code> or <code>.png</code>.</li> </ol>"},{"location":"quickstart/standalone-rule/#testing-file-extensions","title":"Testing file extensions","text":"<p>You can test the rule by using the <code>Invoke-PSRule</code> command. For example:</p> PowerShell<pre><code>$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\n\n# The path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\FileType.Rule.ps1'\n# Or the directory can be used to find all rules in the path:\n# $rulePath = 'C:\\temp\\'\n\n# Test the rule\n$files | Invoke-PSRule -Path $rulePath\n</code></pre> <p>After running <code>Invoke-PSRule</code> you will get output which includes all files in the pathToSeach. Files with a <code>.jpg</code> or <code>.png</code> extension should have the outcome of <code>Fail</code>. All other files should report an outcome of <code>Pass</code>.</p> <p>For example:</p> Output<pre><code>   TargetName: main.html\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nYaml.FileType                       Pass       Image files are not permitted.\n\n   TargetName: favicon.png\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nYaml.FileType                       Fail       Image files are not permitted.\n</code></pre> <p>Tip</p> <ul> <li>If you didn't get any results with <code>Fail</code> try creating or saving a <code>.jpg</code> file in pathToSeach.</li> <li> <p>If you have too many <code>Pass</code> results you can filter the output to only fails by using <code>-Outcome Fail</code>.   For example:</p> <pre><code>$files | Invoke-PSRule -Path $rulePath -Outcome Fail\n</code></pre> </li> </ul>"},{"location":"quickstart/standalone-rule/#scenario-test-for-service-status","title":"Scenario - Test for service status","text":"<p> v2.0.0</p> <p>In our quickstart scenario, we have been tasked to:</p> <ul> <li>Find any services that are set to start automatically with <code>StartType</code> beginning with <code>Automatic</code>.</li> <li>Fail for any service with a <code>Status</code> other than <code>Running</code>.</li> </ul> <p>We will be using the following PowerShell code to get a list of local services.</p> PowerShell<pre><code>$services = Get-Service\n</code></pre> <p>Note</p> <p>This scenario is designed for Windows clients. The PowerShell cmdlet <code>Get-Service</code> is only available on Windows.</p>"},{"location":"quickstart/standalone-rule/#define-a-selector","title":"Define a selector","text":"<p>A selector can be used to filter a list of all services to only services that are set to start automatically. Selectors use YAML or JSON expressions and are similar to rules in many ways. A selector determines if the rule will be run or skipped.</p> <ul> <li>If the selector is <code>true</code> then the rule will be run and either pass or fail.</li> <li>If the selector is <code>false</code> then the rule will be skipped.</li> </ul> YAMLJSON <p>Create the <code>Service.Rule.yaml</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>Service.Rule.yaml</code>.</p> YAML<pre><code>---\n# Synopsis: Find services with an automatic start type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.IsAutomaticService\nspec:\n  if:\n    field: StartType\n    startsWith: Automatic\n    convert: true\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your selector in a line comment above your rule.</li> <li>Name your selector with a unique name <code>Yaml.IsAutomaticService</code>.</li> <li>The <code>if</code> property determines if PSRule will evaluate the service rule.     Specifically, the <code>StartType</code> property of each service object will be compared.     The value of <code>StartType</code> must start with <code>Automatic</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>StartType</code> to a string.</li> </ol> <p>Create the <code>Service.Rule.jsonc</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>Service.Rule.jsonc</code>.</p> JSON<pre><code>[\n    {\n        // Synopsis: Find services with an automatic start type.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Selector\",\n        \"metadata\": {\n            \"name\": \"Json.IsAutomaticService\"\n        },\n        \"spec\": {\n            \"if\": {\n                \"field\": \"StartType\",\n                \"startsWith\": \"Automatic\",\n                \"convert\": true\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your selector in a line comment above your rule.</li> <li>Name your selector with a unique name <code>Json.IsAutomaticService</code>.</li> <li>The <code>if</code> property determines if PSRule will evaluate the service rule.     Specifically, the <code>StartType</code> property of each service object will be compared.     The value of <code>StartType</code> must start with <code>Automatic</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>StartType</code> to a string.</li> </ol>"},{"location":"quickstart/standalone-rule/#define-the-service-rule","title":"Define the service rule","text":"<p>Similar to the selector, the <code>Status</code> field will be tested to determine if the service is <code>Running</code>.</p> YAMLJSONPowerShell <p>Append the following contents to the existing <code>Service.Rule.yaml</code> file.</p> YAML<pre><code>---\n# Synopsis: Automatic services should be running.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.ServiceStarted\nspec:\n  with:\n  - Yaml.IsAutomaticService\n  condition:\n    field: Status\n    equals: Running\n    convert: true\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Yaml.ServiceStarted</code>.</li> <li>The <code>with</code> property indicates to only run this rule on selected service objects.     The <code>Yaml.IsAutomaticService</code> selector must first return <code>true</code> otherwise this rule will be skipped.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each service.     Specifically, the <code>Status</code> property will be compared.     The value of <code>Status</code> must be <code>Running</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>Status</code> to a string.</li> </ol> <p>Update the contents of <code>Service.Rule.jsonc</code> to the following.</p> JSON<pre><code>[\n    {\n        // Synopsis: Find services with an automatic start type.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Selector\",\n        \"metadata\": {\n            \"name\": \"Json.IsAutomaticService\"\n        },\n        \"spec\": {\n            \"if\": {\n                \"field\": \"StartType\",\n                \"startsWith\": \"Automatic\",\n                \"convert\": true\n            }\n        }\n    },\n    {\n        // Synopsis: Automatic services should be running.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Json.ServiceStarted\"\n        },\n        \"spec\": {\n            \"with\": [\n                \"Json.IsAutomaticService\"\n            ],\n            \"condition\": {\n                \"field\": \"Status\",\n                \"equals\": \"Running\",\n                \"convert\": true\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Json.ServiceStarted</code>.</li> <li>The <code>with</code> property indicates to only run this rule on selected service objects.     The <code>Json.IsAutomaticService</code> selector must first return <code>true</code> otherwise this rule will be skipped.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each service.     Specifically, the <code>Status</code> property will be compared.     The value of <code>Status</code> must be <code>Running</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>Status</code> to a string.</li> </ol> <p>Create the <code>Service.Rule.ps1</code> file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you save <code>Service.Rule.ps1</code>.</p> PowerShell<pre><code># Synopsis: Automatic services should be running.\nRule 'PS.ServiceStarted' -With 'Yaml.IsAutomaticService' {\n    $status = $TargetObject.Status.ToString()\n    $Assert.HasFieldValue($status, '.', 'Running')\n}\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>PS.ServiceStarted</code>.</li> <li>The <code>-With</code> parameter indicates to only run this rule on selected service objects.     The <code>Yaml.IsAutomaticService</code> selector must first return <code>true</code> otherwise this rule will be skipped.</li> <li>The condition contained within the curly braces <code>{ }</code> determines the checks PSRule will use to test each service object.</li> <li>The <code>Status</code> enum property is converted to a string.</li> <li>The <code>$Assert.HasFieldValue</code> method checks the converted <code>Status</code> property is set to <code>Running</code>.</li> </ol>"},{"location":"quickstart/standalone-rule/#testing-service-objects","title":"Testing service objects","text":"<p>You can test the rule with service object by using the <code>Invoke-PSRule</code> command. For example:</p> PowerShell<pre><code>$services = Get-Service\n\n# The directory path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\'\n\n# Test the rule\n$services | Invoke-PSRule -Path $rulePath\n</code></pre> <p>After running <code>Invoke-PSRule</code> you will get output which include for services that start automatically. Services that are <code>Running</code> should pass whereas other stopped services should fail. For manual or disabled services a warning will be generated indicating that no matching rules were found.</p> <p>For example:</p> Output<pre><code>   TargetName: edgeupdate\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nPS.ServiceStarted                   Fail       Automatic services should be running.\nYaml.ServiceStarted                 Fail       Automatic services should be running.\nJson.ServiceStarted                 Fail       Automatic services should be running.\n\n\n   TargetName: EventLog\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nPS.ServiceStarted                   Pass       Automatic services should be running.\nYaml.ServiceStarted                 Pass       Automatic services should be running.\nJson.ServiceStarted                 Pass       Automatic services should be running.\n\nWARNING: Target object 'TermService' has not been processed because no matching rules were found.\n</code></pre> <p>Tip</p> <p>You can disable the warning by setting Execution.UnprocessedObject option. Alternatively you can ignore all warnings by using the <code>-WarningAction SilentlyContinue</code> parameter.</p>"},{"location":"scenarios/","title":"Getting started with PSRule","text":""},{"location":"scenarios/#define-a-rule","title":"Define a rule","text":"<p>To define a rule, use a <code>Rule</code> block saved to a file with the <code>.Rule.ps1</code> extension.</p> <pre><code>Rule 'NameOfRule' {\n    # Rule conditions\n}\n</code></pre> <p>Within the body of the rule provide one or more conditions. A condition is valid PowerShell that results in <code>$True</code> or <code>$False</code>.</p> <p>For example:</p> <pre><code>Rule 'isFruit' {\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre> <p>An optional result message can be added to by using the <code>Recommend</code> keyword.</p> <pre><code>Rule 'isFruit' {\n    # An recommendation to display in output\n    Recommend 'Fruit is only Apple, Orange and Pear'\n\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre> <p>The rule is saved to a file named <code>isFruit.Rule.ps1</code> file. One or more rules can be defined within a single file.</p>"},{"location":"scenarios/#execute-a-rule","title":"Execute a rule","text":"<p>To execute the rule use <code>Invoke-PSRule</code>.</p> <p>For example:</p> <pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\n</code></pre> <p>The output of this example is:</p> <pre><code>   TargetName: Fridge\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Fail       Fruit is only Apple, Orange and Pear\n\n\n   TargetName: Apple\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Pass       Fruit is only Apple, Orange and Pear\n</code></pre>"},{"location":"scenarios/#additional-options","title":"Additional options","text":"<p>To filter results to only non-fruit results, use <code>Invoke-PSRule -Outcome Fail</code>. Passed, failed and error results are shown by default.</p> <pre><code># Only show non-fruit results\n$items | Invoke-PSRule -Outcome Fail;\n</code></pre> <p>For a summary of results for each rule use <code>Invoke-PSRule -As Summary</code>.</p> <p>For example:</p> <pre><code># Show rule summary\n$items | Invoke-PSRule -As Summary;\n</code></pre> <p>The output of this example is:</p> <pre><code>RuleName                            Pass  Fail  Outcome\n--------                            ----  ----  -------\nisFruit                             1     1     Fail\n</code></pre> <p>An optional failure reason can be added to the rule block by using the <code>Reason</code> keyword.</p> <pre><code>Rule 'isFruit' {\n    # An recommendation to display in output\n    Recommend 'Fruit is only Apple, Orange and Pear'\n\n    # An failure reason to display for non-fruit\n    Reason \"$($PSRule.TargetName) is not fruit.\"\n\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre> <p>To include the reason with output use <code>Invoke-PSRule -OutputFormat Wide</code>.</p> <p>For example:</p> <pre><code># Show failure reason for failing results\n$items | Invoke-PSRule -OutputFormat Wide;\n</code></pre> <p>The output of this example is:</p> <pre><code>   TargetName: Fridge\n\nRuleName                            Outcome    Reason                              Recommendation\n--------                            -------    ------                              --------------\nisFruit                             Fail       Fridge is not fruit.                Fruit is only Apple, Orange and Pear\n\n\n   TargetName: Apple\n\nRuleName                            Outcome    Reason                              Recommendation\n--------                            -------    ------                              --------------\nisFruit                             Pass                                           Fruit is only Apple, Orange and Pear\n</code></pre> <p>The final rule is saved to <code>isFruit.Rule.ps1</code>.</p>"},{"location":"scenarios/#scenarios","title":"Scenarios","text":"<p>For walk through examples of PSRule usage see:</p> <ul> <li>Validate Azure resource configuration</li> <li>Validate Azure resources tags</li> <li>Validate Kubernetes resources</li> <li>Using within continuous integration</li> <li>Packaging rules in a module</li> <li>Writing rule help</li> </ul>"},{"location":"scenarios/azure-resources/azure-resources/","title":"Validate Azure resource configuration","text":"<p>PSRule makes it easy to validate Infrastructure as Code (IaC) such as Azure resources. For example, Azure resources can be validated to match an internal standard or baseline.</p> <p>Note</p> <p>A pre-built module to validate Azure resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.</p> <p>Consider using or contributing these pre-built rule modules instead:</p> <ul> <li>PSRule.Rules.Azure</li> <li>PSRule.Rules.CAF</li> </ul> <p>This scenario covers the following:</p> <ul> <li>Defining a basic rule.</li> <li>Adding a recommendation.</li> <li>Using script pre-conditions.</li> <li>Using helper functions.</li> </ul> <p>In this scenario we will use a JSON file:</p> <ul> <li><code>resources.json</code> - An export for the Azure resource properties saved for offline use.</li> </ul> <p>To generate a similar <code>resources.json</code> file of your own, the use following command.</p> <pre><code># Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path .\\resources.json;\n</code></pre> <p>For this example we ran this command:</p> <pre><code>Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path docs/scenarios/azure-resources/resources.json;\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#define-rules","title":"Define rules","text":"<p>To validate our Azure resources we need to define some rules. Rules are defined by using the <code>Rule</code> keyword in a file ending with the <code>.Rule.ps1</code> extension.</p> <p>So start we are going to define a <code>storageAccounts.UseHttps</code> rule, which will validate that Azure Storage resources have a Secure Transfer Required enabled.</p> <p>In the example below:</p> <ul> <li>We use <code>storageAccounts.UseHttps</code> directly after the <code>Rule</code> keyword to name the rule definition. Each rule must be named uniquely.</li> <li>The <code># Synopsis:</code> comment is used to add additional metadata interpreted by PSRule.</li> <li>One or more conditions are defined within the curly braces <code>{ }</code>.</li> <li>The rule definition is saved within a file named <code>storageAccounts.Rule.ps1</code>.</li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n    # Rule conditions go here\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#set-rule-condition","title":"Set rule condition","text":"<p>Conditions can be any valid PowerShell expression that results in a <code>$True</code> or <code>$False</code>, just like an <code>If</code> statement, but without specifically requiring the <code>If</code> keyword to be used.</p> <p>Several PSRule keywords such as <code>Exists</code> and <code>AllOf</code> can supplement PowerShell to quickly build out rules that are easy to read.</p> <p>In <code>resources.json</code> one of our example storage accounts has a property <code>Properties.supportsHttpsTrafficOnly</code> as shown below, which will be how our rule will pass <code>$True</code> or fail <code>$False</code> Azure resources that we throw at it.</p> <pre><code>{\n    \"Name\": \"storage\",\n    \"ResourceName\": \"storage\",\n    \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n    \"Kind\": \"Storage\",\n    \"ResourceGroupName\": \"test-rg\",\n    \"Location\": \"eastus2\",\n    \"Properties\": {\n        \"supportsHttpsTrafficOnly\": false\n    }\n}\n</code></pre> <p>In the example below:</p> <ul> <li>We use the <code>$TargetObject</code> variable to get the object on the pipeline and access it's properties.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the object passed the validation check</li> <li><code>$False</code> - the object failed the validation check</li> </ul> </li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n    # This property returns true or false, so nothing more needs to be done\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n\n    # Alternatively this could be written as:\n    # $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#add-rule-recommendation","title":"Add rule recommendation","text":"<p>Additionally to provide feedback to the person or process running the rules, we can use the <code>Recommend</code> keyword to set a message that appears in results.</p> <p>If a recommend message is not provided the synopsis will be used instead.</p> <p>In the example below:</p> <ul> <li>Directly after the <code>Recommend</code> keyword is a message to help understand why the rule failed or passed.</li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#filter-with-preconditions","title":"Filter with preconditions","text":"<p>So far our rule works for a Storage Account, but there are many type of resources that could be returned by calling <code>Get-AzResource</code>. Most of these resources won't have the <code>Properties.supportsHttpsTrafficOnly</code> property, and if it did, it may use different configuration options instead of just <code>true</code> and <code>false</code>. This is where preconditions help out.</p> <p>Preconditions can be specified by using the <code>-If</code> parameter when defining a rule. When the rule is executed, if the precondition is <code>$True</code> then the rule is processed, otherwise it is skipped.</p> <p>In the example below:</p> <ul> <li>A check against <code>$TargetObject.ResourceType</code> ensured that our rule is only processed for Storage Accounts.</li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { $TargetObject.ResourceType -eq 'Microsoft.Storage/storageAccounts' } {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre> <p>Skipped rules have the outcome <code>None</code> and are not included in output by default. To include skipped rules use the <code>-Outcome All</code> parameter.</p>"},{"location":"scenarios/azure-resources/azure-resources/#execute-rules","title":"Execute rules","text":"<p>With a rule defined, the next step is to execute it. To execute rules, pipe the target object to <code>Invoke-PSRule</code>.</p> <p>For example:</p> <pre><code># Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Process resources\n$resources | Invoke-PSRule;\n</code></pre> <p>PSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:</p> <pre><code>Invoke-PSRule -InputPath .\\resources.json;\n</code></pre> <p>You will notice, we didn't specify the rule. By default PSRule will look for any <code>.Rule.ps1</code> files in the current working path.</p> <p><code>Invoke-PSRule</code> supports <code>-Path</code>, <code>-Name</code> and <code>-Tag</code> parameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.</p> <p>For this example we ran these commands:</p> <pre><code>Invoke-PSRule -Path docs/scenarios/azure-resources -InputPath docs/scenarios/azure-resources/resources.json;\n</code></pre> <p>Our output looked like this:</p> <pre><code>   TargetName: storage\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nstorageAccounts.UseHttps            Fail       Storage accounts should only allow secure traffic\n</code></pre> <p>In our case <code>storageAccounts.UseHttps</code> returns a <code>Fail</code> outcome because our storage account has <code>supportsHttpsTrafficOnly</code> = <code>false</code>, which is exactly what should happen.</p>"},{"location":"scenarios/azure-resources/azure-resources/#define-helper-functions","title":"Define helper functions","text":"<p>Using helper functions is completely optional and not required in many cases. However, you may prefer to use helper functions when rule conditions or preconditions are complex and hard to understand.</p> <p>To use helper functions use a <code>function</code> block within a file with a <code>.Rule.ps1</code> extension. Any code within <code>.Rule.ps1</code> files called by <code>Invoke-PSRule</code> will be executed, however to make it available for use within a rule, a global scope modifier must be used.</p> <p>For functions this is done by prefixing the function name with <code>global:</code>.</p> <p>For example:</p> <pre><code>function global:NameOfFunction {\n    # Function body\n}\n</code></pre> <p>In our example, we are going to define a <code>ResourceType</code> function in a file named <code>common.Rule.ps1</code>. This function will be used by preconditions to check the type of Azure resource.</p> <pre><code># A custom function to filter by resource type\nfunction global:ResourceType {\n    param (\n        [String]$ResourceType\n    )\n\n    process {\n        return $TargetObject.ResourceType -eq $ResourceType;\n    }\n}\n</code></pre> <p>Updating our existing <code>storageAccounts.UseHttps</code> rule, our rule definition becomes:</p> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#more-information","title":"More information","text":"<ul> <li>storageAccounts.Rule.ps1 - Example rules for validating Azure Storage.</li> <li>appService.Rule.ps1 - Example rules for validating Azure App Service.</li> <li>resources.json - Offline export of Azure resources.</li> <li>common.Rule.ps1 - ResourceType helper function.</li> </ul>"},{"location":"scenarios/azure-tags/azure-tags/","title":"Azure resource tagging example","text":"<p>This is an example of how PSRule can be used to validate tags on Azure resources to match an internal tagging standard.</p> <p>This scenario covers the following:</p> <ul> <li>Defining a basic rule.</li> <li>Basic usage of <code>Exists</code>, <code>Within</code> and <code>Match</code> keywords.</li> <li>Using configuration in a rule definition.</li> <li>Setting configuration in YAML.</li> <li>Running rules with configuration.</li> </ul> <p>In this scenario we will use a JSON file:</p> <ul> <li><code>resources.json</code> - An export of Azure resource properties saved for offline use.</li> </ul> <p>To generate a similar file of your own, the use following command.</p> <pre><code># Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path .\\resources.json;\n</code></pre> <p>For this example, we ran this command:</p> <pre><code>Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path docs/scenarios/azure-resources/resources.json;\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#define-rules","title":"Define rules","text":"<p>To validate our Azure resources, we need to define some rules. Rules are defined by using the <code>Rule</code> keyword in a file ending with the <code>.Rule.ps1</code> extension.</p> <p>Our business rules for Azure resource tagging can be defined with the following dot points:</p> <ul> <li>Tag names should be easy to read and understand.</li> <li>Tag names will use lower-camel/ pascal casing.</li> <li>The following mandatory tags will be used:<ul> <li>environment: An operational environment for systems and services. Valid environments are production, testing and development.</li> <li>costCentre: A allocation account within financial systems used for charging costs to a business unit. A cost centre is a number with 5 digits and can't start with a 0.</li> <li>businessUnit: The name of the organizational unit or team that owns the application/ solution.</li> </ul> </li> </ul> <p>To start we are going to define an <code>environmentTag</code> rule, which will ensure that the environment tag exists and that the value only uses allowed values.</p> <p>In the example below:</p> <ul> <li>We use <code>environmentTag</code> directly after the <code>Rule</code> keyword to name the rule definition. Each rule must be named uniquely.</li> <li>The <code># Synopsis:</code> comment is used to add additional metadata interpreted by PSRule.</li> <li>One or more conditions are defined within the curly braces <code>{ }</code>.</li> <li>The rule definition is saved within a file named <code>azureTags.Rule.ps1</code>.</li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    # Rule conditions go here\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#check-that-tag-exists","title":"Check that tag exists","text":"<p>Conditions can be any valid PowerShell expression that results in a <code>$True</code> or <code>$False</code>, just like an <code>If</code> statement, but without specifically requiring the <code>If</code> keyword to be used.</p> <p>In <code>resources.json</code> one of our example storage accounts has the <code>Tags</code> property as shown below, this is how Azure Resource Manager stores tags for a resource. We will use this property as the basis of our rules to determine if the resource is tagged and what the tag value is.</p> <pre><code>{\n    \"Name\": \"storage\",\n    \"ResourceName\": \"storage\",\n    \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n    \"Tags\": {\n        \"role\": \"deployment\",\n        \"environment\": \"production\"\n    }\n}\n</code></pre> <p>PSRule also defines several additional keywords to supplement PowerShell. These additional keywords help to create readable rules that can be built out quickly.</p> <p>In the example below:</p> <ul> <li>We use the <code>Exists</code> keyword to check if the environment tag exists.</li> <li>The <code>-CaseSensitive</code> switch is also used to ensure that the tag name uses lowercase.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the environment tag exists.</li> <li><code>$False</code> - the environment tag does not exist.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    Exists 'Tags.environment' -CaseSensitive\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#tag-uses-only-allowed-values","title":"Tag uses only allowed values","text":"<p>In our scenario, we have three environments that our environment tag could be set to. In the next example we will ensure that only allowed environment values are used.</p> <p>In the example below:</p> <ul> <li>We use the <code>Within</code> keyword to check if the environment tag uses any of the allowed values.</li> <li>The <code>-CaseSensitive</code> switch is also used to ensure that the tag value is only a lowercase environment name.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - an allowed environment is used.</li> <li><code>$False</code> - the environment tag does not use one of the allowed values.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    Exists 'Tags.environment' -CaseSensitive\n    Within 'Tags.environment' 'production', 'test', 'development' -CaseSensitive\n}\n</code></pre> <p>Alternatively, instead of using the <code>Within</code> keyword the <code>-cin</code> operator could be used. <code>Within</code> provides additional verbose logging, however either syntax is valid.</p> <p>In the example below:</p> <ul> <li><code>$TargetObject</code> automatic variable is used to get the pipeline object being evaluated.</li> <li>We use the <code>-cin</code> operator to check the environment tag only uses allowed values.</li> <li>The <code>-cin</code> operator performs a cases sensitive match on production, test and development.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - an allowed environment is used.</li> <li><code>$False</code> - the environment tag does not use one of the allowed values.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    Exists 'Tags.environment' -CaseSensitive\n    $TargetObject.Tags.environment -cin 'production', 'test', 'development'\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#tag-value-matches-regular-expression","title":"Tag value matches regular expression","text":"<p>For our second rule (<code>costCentreTag</code>), the costCentre tag value must be 5 numbers. We can validate this by using a regular expression.</p> <p>In the example below:</p> <ul> <li>We use the <code>Match</code> keyword to check if the costCentre tag uses a numeric only value with 5 digits, not starting with 0.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the costCentre tag value matches the regular expression.</li> <li><code>$False</code> - the costCentre tag value does not use match the regular expression.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n    Exists 'Tags.costCentre' -CaseSensitive\n    Match 'Tags.costCentre' '^([1-9][0-9]{4})$'\n}\n</code></pre> <p>An alternative way to write the rule would be to use the <code>-match</code> operator instead of the <code>Match</code> keyword. Like the <code>Within</code> keyword, the <code>Match</code> keyword provides additional verbose logging that the <code>-match</code> operator does not provide.</p> <p>In the example below:</p> <ul> <li><code>$TargetObject</code> automatic variable is used to get the pipeline object being evaluated.</li> <li>We use the <code>-match</code> operator to check the costCentre tag value matches the regular expression.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the costCentre tag value matches the regular expression.</li> <li><code>$False</code> - the costCentre tag value does not use match the regular expression.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n    Exists 'Tags.costCentre' -CaseSensitive\n    $TargetObject.Tags.costCentre -match '^([1-9][0-9]{4})$'\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#use-business-unit-name-from-configuration","title":"Use business unit name from configuration","text":"<p>For our third rule (<code>businessUnitTag</code>), the businessUnit must match a valid business unit. A list of business units will be referenced from configuration instead of hard coded in the rule.</p> <p>Configuration can be used within rule definitions by defining configuration in a YAML file then using the automatic variable <code>$Configuration</code>.</p> <p>In the example below:</p> <ul> <li>We use the <code>Within</code> keyword to check if the businessUnit tag uses any of the allowed values.</li> <li><code>allowedBusinessUnits</code> configuration value can be referenced using the syntax <code>$Configuration.allowedBusinessUnits</code>.</li> <li>The rule definition is defined in azureTags.Rule.ps1.</li> <li>YAML configuration is defined in ps-rule.yaml.</li> </ul> <p>An extract from azureTags.Rule.ps1:</p> <pre><code># Synopsis: Resource must have businessUnit tag\nRule 'businessUnitTag' {\n    Exists 'Tags.businessUnit' -CaseSensitive\n    Within 'Tags.businessUnit' $Configuration.allowedBusinessUnits\n}\n</code></pre> <p>An extract from ps-rule.yaml:</p> <pre><code># Configure business units that are allowed\nconfiguration:\n  allowedBusinessUnits:\n  - 'IT Operations'\n  - 'Finance'\n  - 'HR'\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#execute-rules","title":"Execute rules","text":"<p>With a rule defined, the next step is to execute it. To execute rules, pipe the target object to <code>Invoke-PSRule</code>.</p> <p>For example:</p> <pre><code># Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Evaluate each resource against tagging rules\n$resources | Invoke-PSRule -Option .\\ps-rule.yaml;\n</code></pre> <p>The <code>ps-rule.yaml</code> will automatically discovered if it exists in the current working path (i.e. <code>.\\ps-rule.yaml</code>). Alternatively it can be specified with the <code>-Option</code> parameter as show above.</p> <p>PSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:</p> <pre><code># Evaluate each resource against tagging rules\nInvoke-PSRule -InputPath .\\resources.json;\n</code></pre> <p>You will notice, we didn't specify the rule. By default PSRule will look for any <code>.Rule.ps1</code> files in the current working path.</p> <p><code>Invoke-PSRule</code> supports <code>-Path</code>, <code>-Name</code> and <code>-Tag</code> parameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.</p> <p>The <code>-Option</code> parameter allows us to specify a specific YAML configuration file to use.</p> <p>For this example, we ran these commands:</p> <pre><code># Evaluate each resource against tagging rules\nInvoke-PSRule -Path docs/scenarios/azure-tags -InputPath docs/scenarios/azure-tags/resources.json -Outcome Fail -Option docs/scenarios/azure-tags/ps-rule.yaml;\n</code></pre> <p>Our output looked like this:</p> <pre><code>   TargetName: storage\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\ncostCentreTag                       Fail       Resource must have costCentre tag\nbusinessUnitTag                     Fail       Resource must have businessUnit tag\n\n\n   TargetName: web-app\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nenvironmentTag                      Fail       Resource must have environment tag\ncostCentreTag                       Fail       Resource must have costCentre tag\n\n\n   TargetName: web-app/staging\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nenvironmentTag                      Fail       Resource must have environment tag\ncostCentreTag                       Fail       Resource must have costCentre tag\n</code></pre> <p>Any resources that don't follow the tagging standard are reported with an outcome of <code>Fail</code>.</p>"},{"location":"scenarios/azure-tags/azure-tags/#more-information","title":"More information","text":"<ul> <li>azureTags.Rule.ps1 - Example rules for validating Azure resource tagging standard rules.</li> <li>resources.json - Offline export of Azure resources.</li> <li>ps-rule.yaml - A YAML configuration file for PSRule.</li> </ul>"},{"location":"scenarios/benchmark/results-v0.17.0/","title":"Results v0.17.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.18363.778 (1909/November2018Update/19H2)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=3.1.201\n  [Host]     : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n  DefaultJob : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n</code></pre> |                   Method |       Mean |     Error |    StdDev |     Median |      Gen 0 | Gen 1 | Gen 2 |   Allocated | |------------------------- |-----------:|----------:|----------:|-----------:|-----------:|------:|------:|------------:| |                   Invoke | 111.140 ms | 2.1935 ms | 4.5786 ms | 109.312 ms |  8200.0000 |     - |     - | 16839.42 KB | |                 InvokeIf | 117.141 ms | 2.2703 ms | 2.2298 ms | 116.398 ms |  9600.0000 |     - |     - | 19980.62 KB | |               InvokeType | 108.648 ms | 0.7983 ms | 0.7467 ms | 108.584 ms |  8200.0000 |     - |     - | 16870.67 KB | |            InvokeSummary | 107.300 ms | 0.8612 ms | 0.8056 ms | 107.115 ms |  8000.0000 |     - |     - | 16784.76 KB | |                      Get |   9.003 ms | 0.0643 ms | 0.0602 ms |   9.010 ms |   140.6250 |     - |     - |   307.96 KB | |                  GetHelp |   8.902 ms | 0.0831 ms | 0.0649 ms |   8.899 ms |   140.6250 |     - |     - |   306.34 KB | |                   Within | 179.522 ms | 1.5483 ms | 1.4483 ms | 179.981 ms | 15666.6667 |     - |     - | 32400.38 KB | |               WithinBulk | 247.883 ms | 2.6279 ms | 2.1944 ms | 248.124 ms | 28500.0000 |     - |     - | 59306.73 KB | |               WithinLike | 238.815 ms | 2.5538 ms | 1.9939 ms | 239.245 ms | 29333.3333 |     - |     - | 60580.58 KB | | DefaultTargetNameBinding |   2.124 ms | 0.0214 ms | 0.0200 ms |   2.129 ms |    85.9375 |     - |     - |   179.69 KB | |  CustomTargetNameBinding |   2.463 ms | 0.0483 ms | 0.0452 ms |   2.458 ms |   179.6875 |     - |     - |      375 KB | |  NestedTargetNameBinding |   2.433 ms | 0.0370 ms | 0.0328 ms |   2.420 ms |   179.6875 |     - |     - |      375 KB |</p>"},{"location":"scenarios/benchmark/results-v0.19.0/","title":"Results v0.19.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n  [Host]     : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  40,943.5 \u03bcs |   581.23 \u03bcs |   515.25 \u03bcs |  4000.0000 | 500.0000 |     - | 16452.28 KB | |                 InvokeIf |  42,806.0 \u03bcs |   477.29 \u03bcs |   423.11 \u03bcs |  4500.0000 | 500.0000 |     - | 18703.12 KB | |               InvokeType |  40,470.1 \u03bcs |   484.16 \u03bcs |   429.19 \u03bcs |  4000.0000 | 538.4615 |     - | 16452.27 KB | |            InvokeSummary |  39,768.8 \u03bcs |   462.14 \u03bcs |   385.91 \u03bcs |  4000.0000 | 153.8462 |     - | 16397.82 KB | |                      Get |  11,145.4 \u03bcs |   402.59 \u03bcs | 1,187.03 \u03bcs |    46.8750 |        - |     - |   252.11 KB | |                  GetHelp |  10,169.1 \u03bcs |   625.02 \u03bcs | 1,842.88 \u03bcs |    46.8750 |        - |     - |   250.51 KB | |                   Within |  78,993.5 \u03bcs |   799.51 \u03bcs |   667.63 \u03bcs |  8000.0000 | 400.0000 |     - | 32791.83 KB | |               WithinBulk | 118,800.8 \u03bcs | 1,637.36 \u03bcs | 1,531.59 \u03bcs | 14333.3333 | 333.3333 |     - | 59817.29 KB | |               WithinLike | 106,796.3 \u03bcs | 2,067.20 \u03bcs | 2,538.71 \u03bcs | 11333.3333 |        - |     - | 47311.07 KB | | DefaultTargetNameBinding |     698.2 \u03bcs |     7.51 \u03bcs |     7.02 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     884.7 \u03bcs |     7.11 \u03bcs |     6.65 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     883.9 \u03bcs |    14.44 \u03bcs |    12.80 \u03bcs |    85.9375 |        - |     - |   351.56 KB |</p>"},{"location":"scenarios/benchmark/results-v0.20.0/","title":"Results v0.20.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n  [Host]     : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |     Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|------:|------------:| |                   Invoke |  42,162.8 \u03bcs |   827.36 \u03bcs | 1,263.47 \u03bcs |  3833.3333 |         - |     - |    15952 KB | |                 InvokeIf |  45,646.4 \u03bcs |   912.31 \u03bcs | 1,924.38 \u03bcs |  4416.6667 |  416.6667 |     - | 18202.98 KB | |               InvokeType |  41,825.5 \u03bcs |   810.73 \u03bcs |   901.12 \u03bcs |  3833.3333 |         - |     - |    15952 KB | |            InvokeSummary |  41,133.3 \u03bcs |   777.97 \u03bcs |   895.91 \u03bcs |  3833.3333 |  500.0000 |     - | 15897.56 KB | |                      Get |  10,054.3 \u03bcs |   396.83 \u03bcs | 1,170.07 \u03bcs |    46.8750 |         - |     - |   252.11 KB | |                  GetHelp |  10,581.4 \u03bcs |   448.15 \u03bcs | 1,321.38 \u03bcs |    46.8750 |         - |     - |   250.51 KB | |                   Within |  81,215.1 \u03bcs | 1,532.85 \u03bcs | 1,433.83 \u03bcs |  7750.0000 |  250.0000 |     - | 32290.62 KB | |               WithinBulk | 123,301.6 \u03bcs | 2,451.51 \u03bcs | 3,958.73 \u03bcs | 14000.0000 | 1000.0000 |     - | 59317.29 KB | |               WithinLike | 109,738.9 \u03bcs | 1,933.95 \u03bcs | 1,809.02 \u03bcs | 11333.3333 | 1000.0000 |     - | 46811.07 KB | | DefaultTargetNameBinding |     696.0 \u03bcs |    12.06 \u03bcs |    10.69 \u03bcs |    38.0859 |         - |     - |   156.25 KB | |  CustomTargetNameBinding |     845.6 \u03bcs |    11.75 \u03bcs |    10.42 \u03bcs |    85.9375 |         - |     - |   351.56 KB | |  NestedTargetNameBinding |     856.0 \u03bcs |    12.29 \u03bcs |    10.90 \u03bcs |    85.9375 |         - |     - |   351.56 KB |</p>"},{"location":"scenarios/benchmark/results-v0.21.0/","title":"Results v0.21.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n  [Host]     : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  41,409.3 \u03bcs |   743.11 \u03bcs | 1,089.24 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.02 KB | |                 InvokeIf |  43,138.3 \u03bcs |   510.44 \u03bcs |   426.24 \u03bcs |  4416.6667 |  83.3333 |     - | 18374.86 KB | |               InvokeType |  41,511.3 \u03bcs |   703.93 \u03bcs |   963.55 \u03bcs |  3923.0769 | 230.7692 |     - | 16144.62 KB | |            InvokeSummary |  40,319.9 \u03bcs |   795.95 \u03bcs |   705.59 \u03bcs |  3900.0000 | 500.0000 |     - | 16124.26 KB | |                      Get |   9,873.7 \u03bcs |   392.08 \u03bcs | 1,149.89 \u03bcs |    46.8750 |        - |     - |   253.44 KB | |                  GetHelp |   9,943.1 \u03bcs |   406.36 \u03bcs | 1,198.17 \u03bcs |    46.8750 |        - |     - |   251.84 KB | |                   Within |  76,627.6 \u03bcs | 1,527.91 \u03bcs | 1,759.54 \u03bcs |  7800.0000 |        - |     - | 32460.47 KB | |               WithinBulk | 115,374.0 \u03bcs | 2,279.41 \u03bcs | 3,269.07 \u03bcs | 14333.3333 |        - |     - | 59488.54 KB | |               WithinLike | 102,684.3 \u03bcs | 1,482.11 \u03bcs | 1,313.85 \u03bcs | 11500.0000 | 750.0000 |     - |  46983.1 KB | | DefaultTargetNameBinding |     673.8 \u03bcs |     4.27 \u03bcs |     3.79 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     888.9 \u03bcs |    15.31 \u03bcs |    12.78 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     901.3 \u03bcs |     9.04 \u03bcs |     8.01 \u03bcs |    85.9375 |        - |     - |   351.56 KB |</p>"},{"location":"scenarios/benchmark/results-v0.22.0/","title":"Results v0.22.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n  [Host]     : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  40,804.1 \u03bcs |   656.89 \u03bcs |   614.45 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.02 KB | |                 InvokeIf |  42,768.8 \u03bcs |   843.79 \u03bcs |   704.61 \u03bcs |  4461.5385 |  76.9231 |     - | 18374.92 KB | |               InvokeType |  40,487.0 \u03bcs |   609.33 \u03bcs | 1,034.69 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |            InvokeSummary |  40,403.1 \u03bcs |   806.53 \u03bcs |   714.97 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.26 KB | |                   Assert |  41,551.0 \u03bcs |   684.23 \u03bcs |   640.03 \u03bcs |  4000.0000 | 153.8462 |     - | 16538.36 KB | |                      Get |  10,180.9 \u03bcs |   402.29 \u03bcs | 1,186.17 \u03bcs |    46.8750 |        - |     - |   231.12 KB | |                  GetHelp |   9,941.1 \u03bcs |   409.65 \u03bcs | 1,207.87 \u03bcs |    46.8750 |        - |     - |   229.52 KB | |                   Within |  75,818.3 \u03bcs | 1,504.74 \u03bcs | 2,297.90 \u03bcs |  7800.0000 | 600.0000 |     - | 32468.28 KB | |               WithinBulk | 112,731.0 \u03bcs | 1,239.66 \u03bcs | 1,035.17 \u03bcs | 14333.3333 | 666.6667 |     - | 59496.35 KB | |               WithinLike | 101,227.7 \u03bcs | 1,990.03 \u03bcs | 2,854.05 \u03bcs | 11333.3333 |        - |     - | 46623.62 KB | | DefaultTargetNameBinding |     654.3 \u03bcs |    10.46 \u03bcs |     9.78 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     854.3 \u03bcs |    16.30 \u03bcs |    15.25 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     945.7 \u03bcs |    18.78 \u03bcs |    19.29 \u03bcs |    85.9375 |        - |     - |   351.57 KB | |      AssertHasFieldValue |   1,036.2 \u03bcs |    13.63 \u03bcs |    12.08 \u03bcs |   121.0938 |        - |     - |      500 KB |</p>"},{"location":"scenarios/benchmark/results-v0.3.0/","title":"Results v0.3.0","text":"<p><pre><code>BenchmarkDotNet=v0.11.3, OS=Windows 10.0.17763.195 (1809/October2018Update/Redstone5)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=2.2.100\n  [Host]     : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n  DefaultJob : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n</code></pre> |        Method |       Mean |     Error |    StdDev | Gen 0/1k Op | Gen 1/1k Op | Gen 2/1k Op | Allocated Memory/Op | |-------------- |-----------:|----------:|----------:|------------:|------------:|------------:|--------------------:| |        Invoke | 117.257 ms | 2.1959 ms | 2.1567 ms |   8400.0000 |    400.0000 |           - |         17355.83 KB | |      InvokeIf | 128.418 ms | 3.0122 ms | 3.8095 ms |   9750.0000 |    500.0000 |           - |         20301.73 KB | | InvokeSummary | 116.479 ms | 1.9241 ms | 1.7998 ms |   8400.0000 |           - |           - |         17301.03 KB | |           Get |   8.921 ms | 0.0864 ms | 0.0766 ms |     93.7500 |           - |           - |           203.82 KB |</p>"},{"location":"scenarios/benchmark/results-v1.0.1/","title":"Results v1.0.1","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.102\n  [Host]     : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |       Median |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-------------:|-----------:|---------:|------:|------------:| |                   Invoke |  39,343.5 \u03bcs |   781.08 \u03bcs |   835.75 \u03bcs |  39,287.2 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |                 InvokeIf |  41,264.0 \u03bcs |   545.97 \u03bcs |   483.99 \u03bcs |  41,148.4 \u03bcs |  4461.5385 |  76.9231 |     - | 18374.92 KB | |               InvokeType |  39,514.4 \u03bcs |   755.90 \u03bcs |   670.09 \u03bcs |  39,343.8 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |            InvokeSummary |  39,251.4 \u03bcs |   605.30 \u03bcs |   566.20 \u03bcs |  39,143.5 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.26 KB | |                   Assert |  40,662.2 \u03bcs |   776.24 \u03bcs |   688.12 \u03bcs |  40,589.9 \u03bcs |  4000.0000 | 333.3333 |     - | 16538.53 KB | |                      Get |   8,570.8 \u03bcs |   429.97 \u03bcs | 1,267.78 \u03bcs |   8,872.7 \u03bcs |    46.8750 |        - |     - |   231.12 KB | |                  GetHelp |   9,235.4 \u03bcs |   295.56 \u03bcs |   871.45 \u03bcs |   9,238.7 \u03bcs |    46.8750 |        - |     - |   229.52 KB | |                   Within |  75,171.4 \u03bcs |   744.98 \u03bcs |   660.41 \u03bcs |  75,223.5 \u03bcs |  7750.0000 | 750.0000 |     - | 32468.28 KB | |               WithinBulk | 110,726.9 \u03bcs | 2,142.74 \u03bcs | 2,200.44 \u03bcs | 109,801.1 \u03bcs | 14500.0000 | 500.0000 |     - | 59496.51 KB | |               WithinLike | 101,989.2 \u03bcs | 2,007.91 \u03bcs | 4,056.09 \u03bcs | 100,288.9 \u03bcs | 11250.0000 |        - |     - | 46623.25 KB | | DefaultTargetNameBinding |     626.0 \u03bcs |    11.49 \u03bcs |    10.75 \u03bcs |     622.9 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     796.3 \u03bcs |     7.48 \u03bcs |     7.00 \u03bcs |     797.0 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     806.1 \u03bcs |    12.12 \u03bcs |    10.12 \u03bcs |     805.3 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |      AssertHasFieldValue |     900.6 \u03bcs |    14.51 \u03bcs |    12.87 \u03bcs |     901.2 \u03bcs |   122.0703 |        - |     - |      500 KB |</p>"},{"location":"scenarios/benchmark/results-v1.1.0/","title":"Results v1.1.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.103\n  [Host]     : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  40,327.3 \u03bcs |   801.24 \u03bcs | 1,013.31 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |                 InvokeIf |  42,943.9 \u03bcs |   849.72 \u03bcs | 1,396.11 \u03bcs |  4461.5385 |  76.9231 |     - | 18374.92 KB | |               InvokeType |  40,880.7 \u03bcs |   783.51 \u03bcs | 1,452.28 \u03bcs |  3900.0000 |        - |     - | 16149.45 KB | |            InvokeSummary |  39,101.4 \u03bcs |   431.56 \u03bcs |   336.93 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.26 KB | |                   Assert |  41,917.1 \u03bcs |   831.37 \u03bcs | 1,192.33 \u03bcs |  4076.9231 | 461.5385 |     - | 16780.81 KB | |                      Get |   9,643.0 \u03bcs |   428.32 \u03bcs | 1,262.91 \u03bcs |    54.6875 |   7.8125 |     - |   231.12 KB | |                  GetHelp |   9,271.5 \u03bcs |   372.94 \u03bcs | 1,099.63 \u03bcs |    46.8750 |        - |     - |   229.52 KB | |                   Within |  76,020.5 \u03bcs |   954.22 \u03bcs |   744.99 \u03bcs |  7800.0000 | 600.0000 |     - | 32468.65 KB | |               WithinBulk | 112,135.7 \u03bcs | 2,189.72 \u03bcs | 2,342.97 \u03bcs | 14500.0000 | 500.0000 |     - | 59499.77 KB | |               WithinLike | 101,928.4 \u03bcs | 1,952.97 \u03bcs | 2,398.43 \u03bcs | 11333.3333 |        - |     - | 46623.57 KB | | DefaultTargetNameBinding |     655.6 \u03bcs |    13.11 \u03bcs |    25.87 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     822.1 \u03bcs |    16.06 \u03bcs |    19.11 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     878.9 \u03bcs |    16.63 \u03bcs |    17.08 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |      AssertHasFieldValue |     923.2 \u03bcs |    17.81 \u03bcs |    19.05 \u03bcs |   122.0703 |   0.9766 |     - |   500.26 KB |</p>"},{"location":"scenarios/benchmark/results-v1.10.0/","title":"Results v1.10.0","text":"<p><pre><code>BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n  [Host]     : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |     Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| |                   Invoke |  50,742.5 \u03bcs |   908.47 \u03bcs |   709.27 \u03bcs |  4100.0000 |  400.0000 | 17,758 KB | |                 InvokeIf |  53,048.6 \u03bcs |   698.34 \u03bcs |   619.06 \u03bcs |  4500.0000 |  200.0000 | 20,008 KB | |               InvokeType |  50,575.6 \u03bcs |   794.27 \u03bcs |   663.25 \u03bcs |  4000.0000 |  200.0000 | 17,760 KB | |            InvokeSummary |  50,449.0 \u03bcs |   698.80 \u03bcs |   619.47 \u03bcs |  4100.0000 |  400.0000 | 17,758 KB | |                   Assert |  52,152.6 \u03bcs |   765.95 \u03bcs |   678.99 \u03bcs |  4200.0000 |  300.0000 | 18,462 KB | |                      Get |   5,793.8 \u03bcs |    86.70 \u03bcs |    81.10 \u03bcs |    78.1250 |         - |    364 KB | |                  GetHelp |   5,799.6 \u03bcs |    76.72 \u03bcs |    71.77 \u03bcs |    85.9375 |    7.8125 |    364 KB | |                   Within |  89,538.2 \u03bcs | 1,754.26 \u03bcs | 1,555.11 \u03bcs |  8000.0000 | 1000.0000 | 34,102 KB | |               WithinBulk | 128,126.9 \u03bcs | 1,928.80 \u03bcs | 1,709.83 \u03bcs | 14666.6667 | 1333.3333 | 61,131 KB | |               WithinLike | 112,174.1 \u03bcs | 1,132.30 \u03bcs | 1,003.76 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding |     695.6 \u03bcs |    13.57 \u03bcs |    14.52 \u03bcs |    38.0859 |         - |    156 KB | |  CustomTargetNameBinding |     851.0 \u03bcs |    10.35 \u03bcs |     8.64 \u03bcs |    85.9375 |         - |    352 KB | |  NestedTargetNameBinding |     961.5 \u03bcs |    17.83 \u03bcs |    15.80 \u03bcs |    85.9375 |         - |    352 KB | |      AssertHasFieldValue |   3,033.5 \u03bcs |    60.15 \u03bcs |    66.85 \u03bcs |   253.9063 |    7.8125 |  1,040 KB |</p>"},{"location":"scenarios/benchmark/results-v1.11.0/","title":"Results v1.11.0","text":"<p><pre><code>BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n  [Host]     : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |     Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| |                   Invoke |  50,529.4 \u03bcs | 1,006.40 \u03bcs |   941.38 \u03bcs |  4000.0000 |  444.4444 | 17,758 KB | |                 InvokeIf |  51,974.4 \u03bcs |   667.26 \u03bcs |   591.51 \u03bcs |  4500.0000 |  200.0000 | 20,008 KB | |               InvokeType |  49,901.2 \u03bcs |   679.83 \u03bcs |   567.69 \u03bcs |  4000.0000 |  363.6364 | 17,758 KB | |            InvokeSummary |  51,198.9 \u03bcs |   862.22 \u03bcs |   922.57 \u03bcs |  4000.0000 |  363.6364 | 17,758 KB | |                   Assert |  52,136.6 \u03bcs |   588.93 \u03bcs |   550.88 \u03bcs |  4100.0000 |  300.0000 | 18,461 KB | |                      Get |   5,710.0 \u03bcs |   111.69 \u03bcs |   104.47 \u03bcs |    85.9375 |    7.8125 |    364 KB | |                  GetHelp |   5,777.4 \u03bcs |    97.83 \u03bcs |    91.51 \u03bcs |    85.9375 |    7.8125 |    364 KB | |                   Within |  88,106.3 \u03bcs | 1,752.66 \u03bcs | 1,799.86 \u03bcs |  8000.0000 | 1000.0000 | 34,102 KB | |               WithinBulk | 125,319.9 \u03bcs | 2,303.80 \u03bcs | 2,154.98 \u03bcs | 14666.6667 | 1000.0000 | 61,133 KB | |               WithinLike | 115,376.3 \u03bcs | 1,866.04 \u03bcs | 1,654.20 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding |     669.5 \u03bcs |     6.52 \u03bcs |     6.10 \u03bcs |    38.0859 |         - |    156 KB | |  CustomTargetNameBinding |     837.6 \u03bcs |     6.70 \u03bcs |     6.27 \u03bcs |    85.9375 |         - |    352 KB | |  NestedTargetNameBinding |     854.1 \u03bcs |     9.50 \u03bcs |     7.42 \u03bcs |    85.9375 |         - |    352 KB | |      AssertHasFieldValue |   2,967.0 \u03bcs |    38.88 \u03bcs |    34.47 \u03bcs |   253.9063 |    7.8125 |  1,040 KB |</p>"},{"location":"scenarios/benchmark/results-v2.0.0/","title":"Results v2.0.0","text":"<p><pre><code>BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=6.0.400\n  [Host]     : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\n</code></pre> |                   Method |             Mean |           Error |           StdDev |           Median |      Gen 0 |     Gen 1 | Allocated | |------------------------- |-----------------:|----------------:|-----------------:|-----------------:|-----------:|----------:|----------:| |                   Invoke |  71,586,583.6 ns | 4,077,161.43 ns | 11,957,608.68 ns |  71,526,200.0 ns |  4200.0000 |  600.0000 | 17,703 KB | |                 InvokeIf |  59,661,136.5 ns | 1,161,506.18 ns |  1,192,781.33 ns |  59,397,680.0 ns |  4400.0000 |  400.0000 | 19,954 KB | |               InvokeType |  55,089,186.0 ns | 1,045,769.22 ns |  1,989,684.63 ns |  54,242,620.0 ns |  4300.0000 |  500.0000 | 17,703 KB | |            InvokeSummary |  55,371,580.7 ns | 1,271,559.50 ns |  3,586,456.14 ns |  53,815,745.0 ns |  4300.0000 |  500.0000 | 17,704 KB | |                   Assert |  56,146,053.8 ns | 1,122,221.08 ns |  3,053,085.20 ns |  54,841,105.0 ns |  4500.0000 |  600.0000 | 18,407 KB | |                      Get |   5,701,341.2 ns |   110,332.76 ns |    158,235.95 ns |   5,665,673.8 ns |    78.1250 |    7.8125 |    365 KB | |                  GetHelp |   5,750,066.9 ns |   113,595.72 ns |    170,024.73 ns |   5,720,298.0 ns |    85.9375 |    7.8125 |    366 KB | |                   Within |  99,151,338.5 ns | 2,136,858.10 ns |  6,165,324.21 ns |  97,015,516.7 ns |  8333.3333 | 1333.3333 | 34,142 KB | |               WithinBulk | 147,062,385.7 ns | 2,633,709.47 ns |  2,334,714.85 ns | 146,838,450.0 ns | 14000.0000 | 3000.0000 | 61,169 KB | |               WithinLike | 120,988,346.7 ns | 2,099,294.17 ns |  1,963,681.06 ns | 120,963,000.0 ns | 11666.6667 | 1666.6667 | 48,297 KB | | DefaultTargetNameBinding |     731,969.9 ns |    13,918.54 ns |     36,422.40 ns |     714,067.8 ns |    38.0859 |         - |    156 KB | |  CustomTargetNameBinding |   1,052,297.9 ns |    44,284.38 ns |    125,627.41 ns |   1,022,416.2 ns |    85.9375 |         - |    352 KB | |  NestedTargetNameBinding |     916,580.7 ns |    24,378.48 ns |     71,497.85 ns |     903,449.3 ns |    85.9375 |         - |    352 KB | |      AssertHasFieldValue |   3,082,706.1 ns |    61,644.86 ns |     68,518.10 ns |   3,058,487.1 ns |   234.3750 |         - |    962 KB | |             PathTokenize |         846.6 ns |        16.52 ns |         23.69 ns |         842.4 ns |     0.2632 |         - |      1 KB | |      PathExpressionBuild |         548.3 ns |        10.14 ns |         11.68 ns |         547.1 ns |     0.3500 |         - |      1 KB | |        PathExpressionGet |     356,089.5 ns |     7,027.54 ns |     11,348.18 ns |     351,085.5 ns |    17.0898 |         - |     70 KB |</p>"},{"location":"scenarios/containers/container-execution/","title":"Using PSRule from a Container","text":"<p>Depending on your development or CI/CD process for your environment you may desire to use PSRules to validate your Infrastructure as Code (IaC) from a container. This document shows how you can use a simple container based on the mcr.microsoft.com/powershell image from Microsoft.</p> <p>In this tutorial we are going to use a simple Ubuntu based PowerShell image to validate an ARM template. We will do this by creating a dockerfile to describe and create a container image that we can then run. When we run the container we will use a volume mount to share our ARM template and test code for the container to then execute the PSRule for Azure against our ARM template and output the results.</p>"},{"location":"scenarios/containers/container-execution/#creating-the-image","title":"Creating the image","text":"<p>Creating an image ready to run PSRules first requires a dockerfile. The below example will use the latest PowerShell image released and install the <code>PSRule</code> and <code>PSRule.Rules.Azure</code> modules.</p> Dockerfile<pre><code># Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\nFROM mcr.microsoft.com/powershell:7.2-ubuntu-22.04\nSHELL [\"pwsh\", \"-command\"]\n\nRUN Install-Module -Name 'PSRule','PSRule.Rules.Azure' -Force\n</code></pre> <p>The below docker command can be used to create the image locally.</p> <pre><code>docker build --tag psrule:latest .\n</code></pre> <p>Note</p> <p>While fine for an example, it is common to always reference a container by a version number and not the <code>latest</code> tag. Using the <code>latest</code> tag may lead to unexpected behavior as version changes occur.</p>"},{"location":"scenarios/containers/container-execution/#create-your-test-script","title":"Create your test script","text":"<p>Create a new directory and add a new file named <code>validate-files.ps1</code>. This file will run the PSRule test for us on our new container image. Add the below code to the file.</p> <pre><code># Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\n&lt;#\n    .SYNOPSIS\n        Create a PSRule AzRuleTemplate data file and run the PSRule.Rules.Azure module rules against the output.\n#&gt;\n\nGet-AzRuleTemplateLink \"$PSScriptRoot/template\" | Export-AzRuleTemplateData -OutputPath \"$PSScriptRoot/out\"\n\nAssert-PSRule -InputPath \"$PSScriptRoot/out/\" -Module 'PSRule.Rules.Azure' -As Summary\n</code></pre> <p>Also, within the new directory add another directory named <code>template</code>. Add any ARM template you would like to test in this directory. For a starting point you can get a template from Azure Quickstart Templates.</p> <p>Your directory should now look like the below.</p> <pre><code>- Directory \n  |--&gt; validate-files.ps1\n  |--&gt; template\n    |--&gt; ARM template...\n</code></pre>"},{"location":"scenarios/containers/container-execution/#run-psrules-in-the-container","title":"Run PSRules in the container","text":"<p>Now we are ready to go! Run the below docker command to test the ARM template.</p> <pre><code>docker run -it --rm -v $PWD/:/src psrule:latest pwsh -file /src/validate-files.ps1\n</code></pre> <p>This command runs the container and the PSRule tests by mounting the directory to the <code>/src</code> path and then executing the <code>validate-files.ps1</code> script.</p> <p>Note</p> <p>The volume mount option expects your current working directory to be the new directory created. You can change this to an absolute or relative path if desired.</p>"},{"location":"scenarios/containers/container-execution/#clean-up","title":"Clean up","text":"<p>When you are ready to clean up the container image you can do so with the below command.</p> <pre><code>docker image rm psrule\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/","title":"Kubernetes resource validation example","text":"<p>This is an example of how PSRule can be used to validate Kubernetes resources to match an internal metadata and configuration standard.</p> <p>Note</p> <p>A pre-built module to validate Kubernetes resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.</p> <p>Consider using or contributing these pre-built rule modules instead:</p> <ul> <li>PSRule.Rules.Kubernetes</li> </ul> <p>This scenario covers the following:</p> <ul> <li>Defining a basic rule.</li> <li>Configuring custom binding.</li> <li>Using a type precondition.</li> <li>Running rules using YAML input.</li> </ul> <p>In this scenario we will use a YAML file:</p> <ul> <li><code>resources.yaml</code> - A Kubernetes manifest containing deployments and services.</li> </ul>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#define-rules","title":"Define rules","text":"<p>To validate our Kubernetes resources, we need to define some rules. Rules are defined by using the <code>Rule</code> keyword in a file ending with the <code>.Rule.ps1</code> extension.</p> <p>Our business rules for configuration Kubernetes resources can be defined with the following dot points:</p> <ul> <li>The following recommended labels will be used on all services and deployments:<ul> <li><code>app.kubernetes.io/name</code> - the name of the application/ service.</li> <li><code>app.kubernetes.io/version</code> - the version of the service.</li> <li><code>app.kubernetes.io/component</code> - identifies the type of component, valid options are <code>web</code>, <code>api</code>, <code>database</code> and <code>gateway</code></li> </ul> </li> <li>For <code>web</code> or <code>api</code> deployments, a minimum of two (2) replicas must be used.</li> <li>Deployments must use container images with a specific version tag, and not <code>latest</code>.</li> <li>Deployments must declare minimum and maximum memory/ CPU resources.</li> </ul> <p>In the example below:</p> <ul> <li>We use <code>metadata.Name</code> directly after the <code>Rule</code> keyword to name the rule definition. Each rule must be named uniquely.</li> <li>The <code># Synopsis:</code> comment is used to add additional metadata interpreted by PSRule.</li> <li>One or more conditions are defined within the curly braces <code>{ }</code>.</li> <li>The rule definition is saved within a file named <code>kubernetes.Rule.ps1</code>.</li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n    # Rule conditions go here\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#check-that-the-label-exists","title":"Check that the label exists","text":"<p>In the next step, we define one or more conditions.</p> <p>Conditions can be:</p> <ul> <li>Any valid PowerShell that returns a true (pass) when the condition is met or false (fail) when the condition is not met.</li> <li>More than one condition can be defined, if any condition returns false then the whole rule fails.</li> </ul> <p>PSRule includes several convenience keywords such as <code>AllOf</code>, <code>AnyOf</code>, <code>Exists</code>, <code>Match</code>, <code>TypeOf</code> and <code>Within</code> that make conditions faster to define, easier to understand and troubleshoot. However, use of these keywords is optional.</p> <p>In the example below:</p> <ul> <li>We use the <code>Exists</code> keyword to check that the resource has the <code>app.kubernetes.io/name</code> label set.<ul> <li>By default, PSRule will step through nested properties separated by a <code>.</code>. i.e. <code>labels</code> is a property of <code>metadata</code>.</li> <li>Kubernetes supports and recommends label namespaces, which often use <code>.</code> in their name. PSRule supports this by enclosing the field name (<code>app.kubernetes.io/name</code>) in apostrophes (<code>'</code>) so that <code>app.kubernetes.io/name</code> is checked instead of <code>app</code>.</li> </ul> </li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>We have also defined something similar for the version and component labels.</p> <p>In the example below:</p> <ul> <li>Double apostrophes (<code>''</code>) are used to enclose <code>app.kubernetes.io/name</code> because the field name uses <code>'</code> at the start and end of the string instead of <code>\"</code> in the previous example.</li> <li>The <code>Within</code> keyword is used to validate that the <code>app.kubernetes.io/component</code> only uses one of four (4) allowed values.</li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/version label\nRule 'metadata.Version' {\n    Exists 'metadata.labels.''app.kubernetes.io/version'''\n}\n\n# Synopsis: Must have the app.kubernetes.io/component label\nRule 'metadata.Component' {\n    Exists 'metadata.labels.''app.kubernetes.io/component'''\n    Within 'metadata.labels.''app.kubernetes.io/component''' 'web', 'api', 'database', 'gateway' -CaseSensitive\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#use-custom-binding","title":"Use custom binding","text":"<p>Before processing rules, PSRule binds <code>TargetName</code> and <code>TargetType</code> properties to the pipeline object. These properties are used for filtering and displaying results.</p> <p>The default properties that PSRule binds are different from how Kubernetes resources are structured. Kubernetes uses:</p> <ul> <li><code>metadata.name</code> to store the name of a resource.</li> <li><code>kind</code> to store the type of resource.</li> </ul> <p>The default bindings can be updated by providing custom property names or a custom script. To change binding property names set the <code>Binding.TargetName</code> and <code>Binding.TargetType</code> configuration options.</p> <p>The following example shows how to set the options using a YAML configuration file:</p> <ul> <li>TargetName is bound to <code>metadata.name</code></li> <li>TargetType is bound to <code>kind</code></li> </ul> <pre><code>binding:\n  targetName:\n  - metadata.name\n  targetType:\n  - kind\n</code></pre> <p>These options can be set in the file <code>.\\ps-rule.yaml</code> to be automatically loaded at when PSRule cmdlets are called. To set these configuration options either edit the file manually or use the following command.</p> <pre><code># Set options in ps-rule.yaml\nSet-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\n</code></pre> <p>Alternatively, these options can be set at runtime using the hashtable syntax.</p> <pre><code># Save options to a variable\n$option = New-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\n</code></pre> <p>These options will be passed to <code>Invoke-PSRule</code> using the <code>-Option</code> parameter in a later step.</p>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#define-preconditions","title":"Define preconditions","text":"<p>Currently the <code>metadata.Name</code> rule defined in a previous step will be executed for any type of object. Kubernetes has many types of built-in resource such as Services, Deployments, Namespaces, Pods and ClusterRoles.</p> <p>By defining a precondition, we can ensure that the rule is only processed for Services or Deployments to match our business rules.</p> <p>PSRule supports two types of preconditions, either type (<code>-Type</code>) or script block (<code>-If</code>).</p> <ul> <li>Type preconditions are one or more type names that PSRule compares to the <code>TargetType</code> binding, where:<ul> <li>One of the type names names equal <code>TargetType</code> the rule will be processed.</li> <li>None of the type names equal <code>TargetType</code> the rule be skipped.</li> </ul> </li> <li>Script block preconditions is a PowerShell script block that returns true or false, where:<ul> <li>True - Continue processing the rule.</li> <li>False - Skip processing the rule.</li> </ul> </li> </ul> <p>Preconditions are evaluated once per rule for each object.</p> <p>In the example below:</p> <ul> <li>We update our <code>metadata.Name</code> rule to use the <code>-Type</code> parameter to specify a type precondition of either Deployment or Service.</li> <li>In a previous step, <code>TypeName</code> was bound to the <code>kind</code> property which will be Deployment or Service for these resource types.</li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>Using a type precondition satisfies our business rules and will deliver faster performance then using a script block. An example using a script block precondition is also shown below.</p> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -If { $TargetObject.kind -eq 'Deployment' -or $TargetObject.kind -eq 'Service' } {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#complete-remaining-rules","title":"Complete remaining rules","text":"<p>The remaining rule definitions from our defined business rules are included below. Each follows a similar pattern and builds on the previous sections.</p> <p>In the example below:</p> <ul> <li>The built-in variable <code>$TargetObject</code> is used to get the current pipeline object.<ul> <li>Built-in keywords like <code>Exists</code> automatically default to <code>$TargetObject</code>, but can be piped alternative input as shown in the rule definition named <code>deployment.ResourcesSet</code>.</li> </ul> </li> </ul> <pre><code># Synopsis: Deployments use a minimum of 2 replicas\nRule 'deployment.HasMinimumReplicas' -Type 'Deployment' {\n    Exists 'spec.replicas'\n    $TargetObject.spec.replicas -ge 2\n}\n\n# Synopsis: Deployments use specific tags\nRule 'deployment.NotLatestImage' -Type 'Deployment' {\n    foreach ($container in $TargetObject.spec.template.spec.containers) {\n        $container.image -like '*:*' -and\n        $container.image -notlike '*:latest'\n    }\n}\n\n# Synopsis: Resource requirements are set for each container\nRule 'deployment.ResourcesSet' -Type 'Deployment' {\n    foreach ($container in $TargetObject.spec.template.spec.containers) {\n        $container | Exists 'resources.requests.cpu'\n        $container | Exists 'resources.requests.memory'\n        $container | Exists 'resources.limits.cpu'\n        $container | Exists 'resources.limits.memory'\n    }\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#execute-rules","title":"Execute rules","text":"<p>With some rules defined, the next step is to execute them. For this example, we'll use <code>Invoke-PSRule</code> to get the result for each rule. The <code>Test-PSRuleTarget</code> cmdlet can be used if only a true or false is required.</p> <p>In our example we are using the YAML format to store Kubernetes resources. PSRule has built-in support for YAML so we can import these files directly from disk or process output from a command such as <code>kubectl</code>.</p> <p>In the examples below:</p> <ul> <li>The <code>-InputPath</code> parameter is used to load objects from disk as YAML. YAML is automatically detected based on the <code>.yaml</code> file extension. Alternatively the <code>-Foramt Yaml</code> parameter can be used.</li> <li>Binding parameters are read from <code>ps-rule.yaml</code> in the current working path. Alternatively the <code>-Option</code> parameter could be used to specify an alternative file path.</li> <li><code>kubectl</code> is called with the <code>-o yaml</code> to output resources as YAML.</li> <li><code>kubectl</code> is piped to <code>Out-String</code> to convert the multi-line output to a single string.</li> <li>The <code>-Format</code> parameter informs PSRule that the string is YAML and it should convert the string into structured objects.</li> <li>The <code>-ObjectPath</code> parameter is used with the output from <code>kubectl</code>. This is required because the output from <code>kubectl</code> is a collection of resources instead of individual resources. Specifically <code>-ObjectPath items</code> gets the resources from the <code>items</code> property of the output.</li> </ul> <pre><code># Validate resources from file\nInvoke-PSRule -InputPath resources.yaml;\n</code></pre> <pre><code># Validate resources directly from kubectl output\nkubectl get services -o yaml | Out-String | Invoke-PSRule -Format Yaml -ObjectPath items;\n</code></pre> <p>For this example, we limited the output to failed results with the following command:</p> <pre><code># Validate resources from file\nInvoke-PSRule -Path docs/scenarios/kubernetes-resources -InputPath docs/scenarios/kubernetes-resources/resources.yaml -Option docs/scenarios/kubernetes-resources/ps-rule.yaml -Outcome Fail;\n</code></pre> <p>The resulting output is:</p> <pre><code>   TargetName: app1-cache\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\ndeployment.HasMinimumReplicas       Fail       Deployments use a minimum of 2 replicas\ndeployment.NotLatestImage           Fail       Deployments use specific tags\ndeployment.ResourcesSet             Fail       Resource requirements are set for each container\n\n\n   TargetName: app1-cache-service\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nmetadata.Name                       Fail       Must have the app.kubernetes.io/name label\nmetadata.Version                    Fail       Must have the app.kubernetes.io/version label\nmetadata.Component                  Fail       Must have the app.kubernetes.io/component label\n\n\n   TargetName: app1-ui\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nmetadata.Version                    Fail       Must have the app.kubernetes.io/version label\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#more-information","title":"More information","text":"<ul> <li>kubernetes.Rule.ps1 - Example rules for validating Kubernetes resources.</li> <li>resources.yaml - An example Kubernetes manifest.</li> <li>ps-rule.yaml - PSRule options configuration file.</li> </ul>"},{"location":"scenarios/validation-pipeline/validation-pipeline/","title":"Using within continuous integration","text":"<p>PSRule supports several features that make it easy to a continuous integration (CI) pipeline. When added to a pipeline, PSRule can validate files, template and objects dynamically.</p> <p>This scenario covers the following:</p> <ul> <li>Installing within a CI pipeline.</li> <li>Validating objects.</li> <li>Formatting output.</li> <li>Failing the pipeline.</li> <li>Generating NUnit output.</li> <li>Additional options.</li> </ul>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#installing-within-a-ci-pipeline","title":"Installing within a CI pipeline","text":"<p>Typically, PSRule is not pre-installed on CI worker nodes and must be installed. If your CI pipeline runs on a persistent virtual machine that you control, consider pre-installing PSRule. The following examples focus on installing PSRule dynamically during execution of the pipeline. Which is suitable for cloud-based CI worker nodes.</p> <p>To install PSRule within a CI pipeline execute the <code>Install-Module</code> PowerShell cmdlet.</p> <p>In the example below:</p> <ul> <li>When installing modules on Windows, modules will be installed into Program Files by default, which requires administrator permissions. Depending on your environment, the CI worker process may not have administrative permissions. Instead we can install PSRule for the current context running the CI pipeline by using the <code>-Scope CurrentUser</code> parameter.</li> <li>By default, this cmdlet will install the module from the PowerShell Gallery which is not trusted by default. Since a CI pipeline is not interactive, use the <code>-Force</code> switch to suppress the confirmation prompt.</li> </ul> <pre><code>Install-Module -Name PSRule -Scope CurrentUser -Force;\n</code></pre> <p>In some cases, installing NuGet and PowerShellGet may be required to connect to the PowerShell Gallery. The NuGet package provider can be installed using the <code>Install-PackageProvider</code> PowerShell cmdlet.</p> <pre><code>Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\nInstall-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n</code></pre> <p>The example below includes both steps together with checks:</p> <pre><code>if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n    Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction Ignore)) {\n    Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\n</code></pre> <pre><code>if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n    Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\n</code></pre> <p>See the change log for the latest version.</p>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validating-objects","title":"Validating objects","text":"<p>To validate objects use <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> or <code>Test-PSRuleTarget</code>. In a CI pipeline, <code>Assert-PSRule</code> is recommended. <code>Assert-PSRule</code> outputs preformatted results ideal for use within a CI pipeline.</p> <p>For rules within the same source control repository, put rules in the <code>.ps-rule</code> directory. A directory <code>.ps-rule</code> in the repository root, is used by convention.</p> <p>In the following example, objects are validated against rules from the <code>./.ps-rule/</code> directory:</p> <pre><code>$items | Assert-PSRule -Path './.ps-rule/'\n</code></pre> <p>Example output:</p> <pre><code> -&gt; ObjectFromFile.psd1 : System.IO.FileInfo\n\n    [PASS] File.Header\n    [PASS] File.Encoding\n    [WARN] Target object 'ObjectFromFile.yaml' has not been processed because no matching rules were found.\n    [WARN] Target object 'ObjectFromNestedFile.yaml' has not been processed because no matching rules were found.\n    [WARN] Target object 'Baseline.Rule.yaml' has not been processed because no matching rules were found.\n\n -&gt; FromFile.Rule.ps1 : System.IO.FileInfo\n\n    [FAIL] File.Header\n    [PASS] File.Encoding\n</code></pre> <p>In the next example, objects from file are validated against pre-defined rules from a module:</p> <pre><code>Assert-PSRule -InputPath .\\resources-*.json -Module PSRule.Rules.Azure;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#formatting-output","title":"Formatting output","text":"<p>When executing a CI pipeline, feedback on any validation failures is important. The <code>Assert-PSRule</code> cmdlet provides easy to read formatted output instead of PowerShell objects.</p> <p>Additionally, <code>Assert-PSRule</code> supports styling formatted output for Azure Pipelines and GitHub Actions. Use the <code>-Style AzurePipelines</code> or <code>-Style GitHubActions</code> parameter to style output.</p> <p>For example:</p> <pre><code>$items | Assert-PSRule -Path './.ps-rule/' -Style AzurePipelines;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#failing-the-pipeline","title":"Failing the pipeline","text":"<p>When using PSRule within a CI pipeline, a failed rule should stop the pipeline. When using <code>Assert-PSRule</code> if any rules fail, an error will be generated.</p> <pre><code>Assert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path ./.ps-rule/\n+          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo          : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\n</code></pre> <p>A single PowerShell error is typically enough to stop a CI pipeline. If you are using a different configuration additionally <code>-ErrorAction Stop</code> can be used.</p> <p>For example:</p> <pre><code>$items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\n</code></pre> <p>Using <code>-ErrorAction Stop</code> will stop the current script and return an exit code of 1.</p> <p>To continue running the current script but return an exit code, use:</p> <pre><code>try {\n    $items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\n}\ncatch {\n    $Host.SetShouldExit(1);\n}\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#generating-nunit-output","title":"Generating NUnit output","text":"<p>NUnit is a popular unit test framework for .NET. NUnit generates a test report format that is widely interpreted by CI systems. While PSRule does not use NUnit directly, it support outputting validation results in the NUnit3 format. Using a common format allows integration with any system that supports the NUnit3 for publishing test results.</p> <p>To generate an NUnit report:</p> <ul> <li>Use the <code>-OutputFormat NUnit3</code> parameter.</li> <li>Use the <code>-OutputPath</code> parameter to specify the path of the report file to write.</li> </ul> <pre><code>$items | Assert-PSRule -Path './.ps-rule/' -OutputFormat NUnit3 -OutputPath reports/rule-report.xml;\n</code></pre> <p>The output path will be created if it does not exist.</p>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#publishing-nunit-report-with-azure-devops","title":"Publishing NUnit report with Azure DevOps","text":"<p>With Azure DevOps, an NUnit report can be published using Publish Test Results task.</p> <p>An example YAML snippet is included below:</p> <pre><code># PSRule results\n- task: PublishTestResults@2\n  displayName: 'Publish PSRule results'\n  inputs:\n    testRunTitle: 'PSRule'\n    testRunner: NUnit\n    testResultsFiles: 'reports/rule-report.xml'\n    mergeTestResults: true\n    publishRunAttachments: true\n  condition: succeededOrFailed()\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#complete-example","title":"Complete example","text":"<p>Putting each of these steps together.</p>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#install-dependencies","title":"Install dependencies","text":"<pre><code># Install dependencies for connecting to PowerShell Gallery\nif ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n    Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction SilentlyContinue)) {\n    Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validate-files","title":"Validate files","text":"<pre><code># Install PSRule module\nif ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n    Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\n\n# Validate files\n$assertParams = @{\n    Path = './.ps-rule/'\n    Style = 'AzurePipelines'\n    OutputFormat = 'NUnit3'\n    OutputPath = 'reports/rule-report.xml'\n}\n$items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n$items | Assert-PSRule $assertParams -ErrorAction Stop;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#azure-devops-pipeline","title":"Azure DevOps Pipeline","text":"<pre><code>steps:\n\n# Install dependencies\n- powershell: ./pipeline-deps.ps1\n  displayName: 'Install dependencies'\n\n# Validate templates\n- powershell: ./validate-files.ps1\n  displayName: 'Validate files'\n\n# Publish pipeline results\n- task: PublishTestResults@2\n  displayName: 'Publish PSRule results'\n  inputs:\n    testRunTitle: 'PSRule'\n    testRunner: NUnit\n    testResultsFiles: 'reports/rule-report.xml'\n    mergeTestResults: true\n    publishRunAttachments: true\n  condition: succeededOrFailed()\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#additional-options","title":"Additional options","text":""},{"location":"scenarios/validation-pipeline/validation-pipeline/#using-invoke-build","title":"Using Invoke-Build","text":"<p>Invoke-Build is a build automation cmdlet that can be installed from the PowerShell Gallery by installing the InvokeBuild module. Within Invoke-Build, each build process is broken into tasks.</p> <p>The following example shows an example of using PSRule with Invoke-Build tasks.</p> <pre><code># Synopsis: Install PSRule\ntask PSRule {\n    if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n        Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n    }\n}\n\n# Synopsis: Validate files\ntask ValidateFiles PSRule, {\n    $assertParams = @{\n        Path = './.ps-rule/'\n        Style = 'AzurePipelines'\n        OutputFormat = 'NUnit3'\n        OutputPath = 'reports/rule-report.xml'\n    }\n    $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n    $items | Assert-PSRule @assertParams -ErrorAction Stop;\n}\n\n# Synopsis: Run all build tasks\ntask Build ValidateFiles\n</code></pre> <pre><code>Invoke-Build Build;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#calling-from-pester","title":"Calling from Pester","text":"<p>Pester is a unit test framework for PowerShell that can be installed from the PowerShell Gallery.</p> <p>Typically, Pester unit tests are built for a particular pipeline. PSRule can complement Pester unit tests by providing dynamic and sharable rules that are easy to reuse. By using <code>-If</code> or <code>-Type</code> pre-conditions, rules can dynamically provide validation for a range of use cases.</p> <p>When calling PSRule from Pester use <code>Invoke-PSRule</code> instead of <code>Assert-PSRule</code>. <code>Invoke-PSRule</code> returns validation result objects that can be tested by Pester <code>Should</code> conditions.</p> <p>Additionally, the <code>Logging.RuleFail</code> option can be included to generate an error message for each failing rule.</p> <p>For example:</p> <pre><code>Describe 'Azure' {\n    Context 'Resource templates' {\n        It 'Use content rules' {\n            $invokeParams = @{\n                Path = './.ps-rule/'\n                OutputFormat = 'NUnit3'\n                OutputPath = 'reports/rule-report.xml'\n            }\n            $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n            Invoke-PSRule @invokeParams -Outcome Fail,Error | Should -BeNullOrEmpty;\n        }\n    }\n}\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#more-information","title":"More information","text":"<ul> <li>pipeline-deps.ps1 - Example script installing pipeline dependencies.</li> <li>file.Rule.ps1 - Example rules for validating script files.</li> <li>validate-files.ps1 - Example script for running files validation.</li> <li>azure-pipelines.yaml - An example Azure DevOps Pipeline.</li> </ul>"},{"location":"specs/design-spec/","title":"PSRule design specification (draft)","text":"<p>This document is intended as a working technical specification for PSRule.</p>"},{"location":"specs/design-spec/#what-is-psrule","title":"What is PSRule?","text":"<p>PSRule is an engine, shipped as a PowerShell module designed to validate infrastructure as code (IaC). Additionally, PSRule can validate any PowerShell object, allowing almost any custom scenario to be supported.</p> <p>PSRule natively supports common infrastructure code artifacts with the following file formats:</p> <ul> <li>YAML (<code>.yaml</code> or <code>.yml</code>).</li> <li>JSON (<code>.json</code>).</li> <li>PowerShell Data Files (<code>.psd1</code>).</li> <li>Markdown front matter (<code>.md</code> or <code>.markdown</code>).</li> </ul> <p>While some infrastructure as code languages implement their own custom language, many support output into a standard artifact format. i.e. <code>terraform show -json</code></p>"},{"location":"specs/design-spec/#project-objectives","title":"Project objectives","text":"<ol> <li>Extensible:<ul> <li>Provide an execution environment (tools and language) to validate infrastructure code.</li> <li>Handling of common concerns such as input/ output/ reporting should be handled by the engine.</li> <li>Language must be flexible enough to support a wide range of use cases.</li> </ul> </li> <li>DevOps:<ul> <li>Validation should support and enhance DevOps workflows by providing fast feedback in pull requests.</li> <li>Allow quality gates to be implemented between environments such development, test, and production.</li> </ul> </li> <li>Cross-platform:<ul> <li>A wide range of platforms can be used to author and deploy infrastructure code. PSRule must support rule validation and authoring on Linux, MacOS, and Windows.</li> <li>Runs in a Linux container. For continuous integration (CI) systems that do not support PowerShell, run in a container.</li> </ul> </li> <li>Reusable:<ul> <li>Validation should plug and play, reusable across teams and organizations.</li> <li>Any reusable validation will have exceptions. Rules must be able to be disabled where they are not applicable.</li> </ul> </li> </ol>"},{"location":"specs/design-spec/#language-specification","title":"Language specification","text":"<p>PSRule is rooted in PowerShell. This provides significant benefits and flexibility including:</p> <ul> <li>Reuses existing skills within Microsoft and customers who already know how to author PowerShell scripts.</li> <li>Builds on existing PowerShell community; allowing existing integrations and cmdlets to be used.</li> <li>PowerShell already has an established model for distributing packages (modules). This includes options for trust and hosting (publicly or privately).</li> </ul> <p>To ensure these benefits remain, the following must be true:</p> <ul> <li>Rules can be written using standard PowerShell operators and conventions. Minimal knowledge of PSRule should be required to author rules.</li> <li>Rules validate an object graph. Whether an object originates from a YAML or JSON file should be abstract.</li> </ul>"},{"location":"specs/design-spec/#future-cases","title":"Future cases","text":"<p>PowerShell offers complete flexibility to build simple to complex rules. However, rule authors may be unfamiliar with PowerShell. Authoring rules in YAML or JSON with a defined schema will allow additional options for basic rules.</p>"},{"location":"specs/design-spec/#concepts","title":"Concepts","text":""},{"location":"specs/design-spec/#rule-definitions","title":"Rule definitions","text":"<p>Rule definitions or rules are defined using PowerShell. Rules can be created in a PowerShell script file with the <code>.Rule.ps1</code> extension. Rule files can be created and used individually or bundled as a module.</p> <p>Each rule:</p> <ul> <li>Implements a test for one or more conditions against an object. When all conditions return true the rule passes, if not the rule fails.</li> <li>Is evaluated by executing the rule within a sandbox that provides context to each rule. Such as the deserialized object being processed and configuration.</li> <li>Can specify preconditions which determine if a rule should be evaluated based on the object being processed. Rules only run against the objects they are designed to test.</li> </ul> <p>For example:</p> <pre><code>Rule 'NameOfRule' {\n    # &lt;Rule conditions&gt;\n}\n</code></pre> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'StorageAccounts.UseHttps' -Type 'Microsoft.Storage/storageAccounts' {\n    $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\n</code></pre>"},{"location":"specs/design-spec/#psrule-engine","title":"PSRule engine","text":"<p>Distributed as a PowerShell module, all source code is included within this repository. This included cmdlets and an execution sandbox where rules are evaluated. PSRule is designed to be self contained, requiring only PowerShell to run.</p> <p>By itself PSRule doesn't implement any specific rules. Custom rules can be defined and evaluated from PowerShell script files. Reusable rules can be distributed using PowerShell modules. Use PowerShellGet to install modules from public and private sources.</p> <p>PSRule extends PowerShell with domain specific language (DSL) keywords, cmdlets, and automatic variables. These language features are only available within the sandbox. Stubs are exported from PSRule module to provide command completion during authoring.</p> <p>In additional to rules, a number of resources can be used within PSRule. Resources are defined in YAML files with the <code>.Rule.yaml</code> file extension. You can create one or many resource within a single <code>.Rule.yaml</code> file.</p> <p>PSRule supports the following resources:</p> <ul> <li><code>Baseline</code> - A reusable group of rules and configuration defaults for a given scenario.</li> <li><code>Selector</code> - A reusable filter to determine which objects a rule should be run against.</li> </ul> <p>A special <code>ModuleConfig</code> resource can also be defined to configure defaults for a module.</p>"},{"location":"specs/design-spec/#keywords-and-variables","title":"Keywords and variables","text":"<p>TBA</p>"},{"location":"specs/design-spec/#baselines","title":"Baselines","text":"<p>A baseline is a resource defined in YAML that determines which rules to run for a given scenario. One or more baselines can be included in a <code>.Rule.yaml</code> file. Baselines can be created individually or bundled in a module.</p> <p>Common use cases where baselines are helpful include:</p> <ul> <li>Separation of rules or features in development. For infrastructure code or rules early in their lifecycle, a recommend practice may not be fully ratified. Baselines allow rules to be distributed but not executed by default.</li> <li>Progressive adoption. If validation has been added for a new use case, it may not be possible to adopt all rules at once. Baselines act as checkpoints to allow validation of a subset of rules.</li> </ul>"},{"location":"specs/design-spec/#execution","title":"Execution","text":"<p>Execution within PSRule occurs within a pipeline. The PSRule pipeline is similar to PowerShell and contains a <code>begin</code>, <code>process</code>, and <code>end</code> stage.</p> <ul> <li>Begin: TBA</li> <li>Process: TBA</li> <li>End: TBA</li> </ul> <p>Three execution pipelines exist, <code>Invoke</code>, <code>Assert</code>, or <code>Test</code>. Differences between each of these pipeline is minimal and mostly deals with how output is presented.</p> <ul> <li>Invoke: Returns output as pipeline objects so they can be natively processed by PowerShell code.</li> <li>Assert: Returns output as styled text to provide readable results within a CI pipeline.</li> <li>Test: Returns true or false based on pass or fail of each object. Use this option to use filter objects from a PowerShell pipeline.</li> </ul>"},{"location":"specs/design-spec/#execution-sandbox","title":"Execution sandbox","text":"<p>The execution sandbox is implemented using PowerShell runspaces. Runspaces are a PowerShell feature which enable partial isolation within a PowerShell process.</p> <p>PSRule uses two discrete runspaces:</p> <ul> <li>In the parent runspace where PSRule is called using <code>Invoke-PSRule</code>, <code>Assert-PSRule</code>, or <code>Test-PSRule</code>. The parent runspace is responsible for all input and output.</li> <li>The sandbox runspace is where rules execute. PSRule keywords and automatic variables are implemented in the sandbox. Flow control within the PSRule pipeline maintains context for each object as it is processed by rules.</li> </ul> <p>Input and output are proxied between the two discrete runspaces to maintain runspace separation. This separation allows rules to be executed without polluting the state of the parent runspace.</p>"},{"location":"specs/design-spec/#rule-evaluation","title":"Rule evaluation","text":"<p>TBA</p>"},{"location":"specs/design-spec/#configuration","title":"Configuration","text":"<p>PSRule has built-in support for configuration of the engine and rules. Configuration can be set by:</p> <ul> <li>Configuring the default <code>ps-rule.yaml</code> file.</li> <li>Setting at runtime by passing a <code>-Option</code> parameter to PSRule cmdlets.</li> </ul>"},{"location":"specs/design-spec/#engine-options","title":"Engine options","text":"<p>Configuration of the PSRule engine is referred to as options. Each option changes the default that PSRule uses during execution. The supported options that can be configured for PSRule are described in the about_PSRule_Options topic.</p>"},{"location":"specs/design-spec/#rule-configuration","title":"Rule configuration","text":"<p>Separately, rules can optionally define configuration that can skip or change the rule conditions. Rule configuration is a key/ value pair.</p>"},{"location":"specs/design-spec/#integration","title":"Integration","text":"<p>TBA</p>"},{"location":"specs/function-spec/","title":"PSRule function expressions spec (draft)","text":"<p>This is a spec for implementing function expressions in PSRule v2.</p>"},{"location":"specs/function-spec/#synopsis","title":"Synopsis","text":"<p>Functions are available to handle complex conditions within YAML and JSON expressions.</p>"},{"location":"specs/function-spec/#schema-driven","title":"Schema driven","text":"<p>While functions allow handing for complex use cases, they should still remain schema driven. A schema driven design allows auto-completion and validation during authoring in a broad set of tools.</p>"},{"location":"specs/function-spec/#syntax","title":"Syntax","text":"<p>Functions can be used within YAML and JSON expressions by using the <code>$</code> object property. For example:</p> <pre><code>---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example1\nspec:\n  if:\n    value:\n      $:\n        substring:\n          path: name\n        length: 3\n    equals: abc\n</code></pre>"},{"location":"specs/option-spec/","title":"PSRule options spec (draft)","text":"<p>This is a spec for implementing options in PSRule v2.</p>"},{"location":"specs/option-spec/#synopsis","title":"Synopsis","text":"<p>When executing resources options is often required to control the specific behaviour. In additional, many of these cases are scoped to the module being used.</p> <p>The following scopes exist:</p> <ul> <li>Parameter</li> <li>Local options</li> <li>Baseline</li> <li>Module configuration</li> </ul>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"CHANGELOG-v0/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Attention</p> <p>PSRule v0 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.</p>"},{"location":"CHANGELOG-v0/#v0220","title":"v0.22.0","text":"<p>What's changed since v0.21.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>HasFields</code> assertion helper to check all fields exist. #578</li> <li>Updated <code>HasField</code> to check if any of the specified fields exist. #578</li> </ul> </li> <li>General improvements:<ul> <li>Input format detection now includes <code>.jsonc</code> and <code>.markdown</code> file extensions. #575</li> <li>Improved support for cross module rule dependencies. #248<ul> <li>Rule dependencies are now automatically imported.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling for null or empty arrays with <code>StartsWith</code>, <code>Contains</code>, <code>EndsWith</code>, <code>In</code>, and <code>NotIn</code>. #579</li> </ul> </li> </ul> <p>What's changed since pre-release v0.22.0-B2010014:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0220-b2010014-pre-release","title":"v0.22.0-B2010014 (pre-release)","text":"<p>What's changed since v0.21.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>HasFields</code> assertion helper to check all fields exist. #578</li> <li>Updated <code>HasField</code> to check if any of the specified fields exist. #578</li> </ul> </li> <li>General improvements:<ul> <li>Input format detection now includes <code>.jsonc</code> and <code>.markdown</code> file extensions. #575</li> <li>Improved support for cross module rule dependencies. #248<ul> <li>Rule dependencies are now automatically imported.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling for null or empty arrays with <code>StartsWith</code>, <code>Contains</code>, <code>EndsWith</code>, <code>In</code>, and <code>NotIn</code>. #579</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210","title":"v0.21.0","text":"<p>What's changed since v0.20.0:</p> <ul> <li>Engine features:<ul> <li>Added support for formatting results as markdown. #474<ul> <li>Use <code>-OutputFormat Markdown</code> or configure <code>Output.Format</code> to output markdown.</li> <li>To format as either detail or summary, use the <code>-As</code> parameter or configure <code>Output.As</code>.</li> </ul> </li> <li>Added character case assertion helpers <code>IsLower</code>, and <code>IsUpper</code>. #555<ul> <li><code>IsLower</code> checks that all letters in a field value are lowercase.</li> <li><code>IsUpper</code> checks that all letters in a field value are uppercase.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Numerical strings can be converted with numeric assertion helpers. #550</li> <li>Added outcome <code>Output.Outcome</code> as a configurable option. #552</li> <li>Added help links and default snippets to schemas. #561</li> <li>Improved rule error reporting by including rule and source location. #565</li> </ul> </li> <li>Engineering:<ul> <li>Bump Manatee.Json from 13.0.2 to 13.0.3. #563</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed NUnit report reasons should be escaped in markdown. #471</li> <li>Fixed reporting of error when rule error is handled. #564<ul> <li>Additionally rules can use <code>-ErrorAction Ignore</code> to ignore non-exception errors.</li> </ul> </li> <li>Fixed first exception stops other rules from being processed. #566</li> </ul> </li> </ul> <p>What's changed since pre-release v0.21.0-B2010010:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2010010-pre-release","title":"v0.21.0-B2010010 (pre-release)","text":"<p>What's changed since pre-release v0.21.0-B2010003:</p> <ul> <li>General improvements:<ul> <li>Improved rule error reporting by including rule and source location. #565</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2010003-pre-release","title":"v0.21.0-B2010003 (pre-release)","text":"<p>What's changed since pre-release v0.21.0-B2009016:</p> <ul> <li>General improvements:<ul> <li>Added help links and default snippets to schemas. #561</li> </ul> </li> <li>Engineering:<ul> <li>Bump Manatee.Json from 13.0.2 to 13.0.3. #563</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed reporting of error when rule error is handled. #564<ul> <li>Additionally rules can use <code>-ErrorAction Ignore</code> to ignore non-exception errors.</li> </ul> </li> <li>Fixed first exception stops other rules from being processed. #566</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2009016-pre-release","title":"v0.21.0-B2009016 (pre-release)","text":"<p>What's changed since pre-release v0.21.0-B2009006:</p> <ul> <li>Engine features:<ul> <li>Added character case assertion helpers <code>IsLower</code>, and <code>IsUpper</code>. #555<ul> <li><code>IsLower</code> checks that all letters in a field value are lowercase.</li> <li><code>IsUpper</code> checks that all letters in a field value are uppercase.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed NUnit report reasons should be escaped in markdown. #471</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0210-b2009006-pre-release","title":"v0.21.0-B2009006 (pre-release)","text":"<p>What's changed since v0.20.0:</p> <ul> <li>Engine features:<ul> <li>Added support for formatting results as markdown. #474<ul> <li>Use <code>-OutputFormat Markdown</code> or configure <code>Output.Format</code> to output markdown.</li> <li>To format as either detail or summary, use the <code>-As</code> parameter or configure <code>Output.As</code>.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Numerical strings can be converted with numeric assertion helpers. #550</li> <li>Added outcome <code>Output.Outcome</code> as a configurable option. #552</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200","title":"v0.20.0","text":"<p>What's changed since v0.19.0:</p> <ul> <li>Engine features:<ul> <li>Added support for scanning repository files. #524<ul> <li>Added <code>File</code> input type (<code>-InputType File</code>) to scan for files without deserializing them.</li> <li>Added <code>Input.PathIgnore</code> option to ignore files.</li> <li>When using the <code>File</code> input type path specs in <code>.gitignore</code> are ignored.</li> </ul> </li> <li>Added <code>Get-PSRuleTarget</code> cmdlet to read input files and return raw objects. #525<ul> <li>This cmdlet can be used to troubleshoot PSRule input issues.</li> </ul> </li> <li>Baselines can now be flagged as obsolete. #499<ul> <li>Set the <code>metadata.annotations.obsolete</code> property to <code>true</code> to flag a baseline as obsolete.</li> <li>When an obsolete baseline is used, a warning will be generated.</li> </ul> </li> <li>Added file assertion helpers <code>FileHeader</code>, and <code>FilePath</code>. #534<ul> <li><code>FileHeader</code> checks for a comment header in the file.</li> <li><code>FilePath</code> checks that a file path (optionally with suffixes) exist.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added automatic binding for Rule object. #542</li> </ul> </li> <li>Engineering:<ul> <li>Warn when deprecated <code>$Rule</code> properties are used. #536 #545<ul> <li>First usage of deprecated property generates a warning.</li> <li>Rule using deprecated property is flagged in debug output.</li> </ul> </li> <li>Bump YamlDotNet dependency to v8.1.2. #439</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed out of bounds exception when empty markdown documentation is used. #516</li> </ul> </li> </ul> <p>What's changed since pre-release v0.20.0-B2009013:</p> <ul> <li>Bug fixes:<ul> <li>Fixed excessive obsolete property warnings. #545</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2009013-pre-release","title":"v0.20.0-B2009013 (pre-release)","text":"<p>What's changed since pre-release v0.20.0-B2009007:</p> <ul> <li>General improvements:<ul> <li>Added automatic binding for Rule object. #542</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>InputFileInfo</code> <code>Type</code> property causes downstream binding issues. #541</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2009007-pre-release","title":"v0.20.0-B2009007 (pre-release)","text":"<p>What's changed since pre-release v0.20.0-B2008010:</p> <ul> <li>Engine features:<ul> <li>Added file assertion helpers <code>FileHeader</code>, and <code>FilePath</code>. #534<ul> <li><code>FileHeader</code> checks for a comment header in the file.</li> <li><code>FilePath</code> checks that a file path (optionally with suffixes) exist.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Warn when deprecated <code>$Rule</code> properties are used. #536</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed out of bounds exception when empty markdown documentation is used. #516</li> <li>Fixed lines breaks in <code>RepositoryInfo</code> target name with git ref. #538</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2008010-pre-release","title":"v0.20.0-B2008010 (pre-release)","text":"<p>What's changed since pre-release v0.20.0-B2008002:</p> <ul> <li>Engine features:<ul> <li>Baselines can now be flagged as obsolete. #499<ul> <li>Set the <code>metadata.annotations.obsolete</code> property to <code>true</code> to flag a baseline as obsolete.</li> <li>When an obsolete baseline is used, a warning will be generated.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to v8.1.2. #439</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0200-b2008002-pre-release","title":"v0.20.0-B2008002 (pre-release)","text":"<p>What's changed since v0.19.0:</p> <ul> <li>Engine features:<ul> <li>Added support for scanning repository files. #524<ul> <li>Added <code>File</code> input type (<code>-InputType File</code>) to scan for files without deserializing them.</li> <li>Added <code>Input.PathIgnore</code> option to ignore files.</li> <li>When using the <code>File</code> input type path specs in <code>.gitignore</code> are ignored.</li> </ul> </li> <li>Added <code>Get-PSRuleTarget</code> cmdlet to read input files and return raw objects. #525<ul> <li>This cmdlet can be used to troubleshoot PSRule input issues.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190","title":"v0.19.0","text":"<p>What's changed since v0.18.1:</p> <ul> <li>Engine features:<ul> <li>Added <code>Reason</code> method to assertion results. #500<ul> <li>This new method, streamlines setting custom reasons particularly with formatted strings.</li> <li>The <code>Reason</code> method replaces any previously set reasons with a custom string.</li> <li>Optional arguments can be provided to be included in string formatting.</li> </ul> </li> <li>Improvements to assertion methods.<ul> <li>Added regular expression assertion helpers <code>Match</code>, and <code>NotMatch</code>. #502</li> <li>Added collection assertion helpers <code>In</code>, and <code>NotIn</code>. #501</li> </ul> </li> <li>Added module version constraints. #498<ul> <li>The module versions that PSRule uses can be constrained.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed styling for no rule files warning with <code>Assert-PSRule</code>. #484</li> <li>Fixed actual value in reason for numeric comparison assertion method. #505</li> </ul> </li> </ul> <p>What's changed since pre-release v0.19.0-B2007030:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2007030-pre-release","title":"v0.19.0-B2007030 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed <code>Assert.In</code> unable to compare PSObject wrapped array items. #512</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2007023-pre-release","title":"v0.19.0-B2007023 (pre-release)","text":"<ul> <li>Engine features:<ul> <li>Added <code>Reason</code> method to assertion results. #500<ul> <li>This new method, streamlines setting custom reasons particularly with formatted strings.</li> <li>The <code>Reason</code> method replaces any previously set reasons with a custom string.</li> <li>Optional arguments can be provided to be included in string formatting.</li> </ul> </li> <li>Improvements to assertion methods.<ul> <li>Added regular expression assertion helpers <code>Match</code>, and <code>NotMatch</code>. #502</li> <li>Added collection assertion helpers <code>In</code>, and <code>NotIn</code>. #501</li> </ul> </li> <li>Added module version constraints. #498<ul> <li>The module versions that PSRule uses can be constrained.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed styling for no rule files warning with <code>Assert-PSRule</code>. #484</li> <li>Fixed actual value in reason for numeric comparison assertion method. #505</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0181","title":"v0.18.1","text":"<p>What's changed since v0.18.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed unable to read properties for .NET <code>DynamicObject</code>. #491</li> <li>Fixed read of JSON input format with null array item. #490</li> <li>Fixed <code>Csv</code> output format with summary for <code>Invoke-PSRule</code>. #486</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2006027-pre-release","title":"v0.19.0-B2006027 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed unable to read properties for .NET <code>DynamicObject</code>. #491</li> <li>Fixed read of JSON input format with null array item. #490</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0190-b2006018-pre-release","title":"v0.19.0-B2006018 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed <code>Csv</code> output format with summary for <code>Invoke-PSRule</code>. #486</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0180","title":"v0.18.0","text":"<p>What's changed since v0.17.0:</p> <ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting. #472<ul> <li>Added recommendation and reasons for <code>AzurePipelines</code> and <code>GitHubActions</code> styles.</li> <li>Summary line is has been updated to include synopsis instead of reasons.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed binding with <code>ModuleConfig</code>. #468</li> <li>Fixed recommendation output with client style. #467</li> </ul> </li> </ul> <p>What's changed since pre-release v0.18.0-B2005015:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0180-b2005015-pre-release","title":"v0.18.0-B2005015 (pre-release)","text":"<ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting. #472<ul> <li>Added recommendation and reasons for <code>AzurePipelines</code> and <code>GitHubActions</code> styles.</li> <li>Summary line is has been updated to include synopsis instead of reasons.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed binding with <code>ModuleConfig</code>. #468</li> <li>Fixed recommendation output with client style. #467</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0170","title":"v0.17.0","text":"<p>What's changed since v0.16.0:</p> <ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting.<ul> <li>Added recommendation and reasons for <code>Client</code> and <code>Plain</code> styles. #456</li> </ul> </li> <li>Added support for configuration of default module options. #459<ul> <li><code>binding</code> and <code>configuration</code> options can be set to a default value.</li> <li>Updated <code>New-PSRuleOption</code> parameter sets and help based on updates to module config.</li> </ul> </li> <li>Added support for module fallback culture. #441</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed resource schema to include <code>useQualifiedName</code> and <code>nameSeparator</code> option. #458</li> </ul> </li> </ul> <p>What's changed since pre-release v0.17.0-B2005010:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0170-b2005010-pre-release","title":"v0.17.0-B2005010 (pre-release)","text":"<ul> <li>General improvements:<ul> <li>Improved <code>Assert-PSRule</code> output formatting.<ul> <li>Added recommendation and reasons for <code>Client</code> and <code>Plain</code> styles. #456</li> </ul> </li> <li>Added support for configuration of default module options. #459<ul> <li><code>binding</code> and <code>configuration</code> options can be set to a default value.</li> <li>Updated <code>New-PSRuleOption</code> parameter sets and help based on updates to module config.</li> </ul> </li> <li>Added support for module fallback culture. #441</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed resource schema to include <code>useQualifiedName</code> and <code>nameSeparator</code> option. #458</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0160","title":"v0.16.0","text":"<p>What's changed since v0.15.0:</p> <ul> <li>General improvements:<ul> <li>Added configuration option <code>Output.Culture</code> for setting culture. #442</li> <li>Improved handling of fields to allow the input object to be referenced with <code>.</code>. #437</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed numeric comparison assertion with non-int types. #436</li> <li>Fixed output culture option ignored. #449</li> </ul> </li> </ul> <p>What's changed since pre-release v0.16.0-B2003027:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0160-b2003027-pre-release","title":"v0.16.0-B2003027 (pre-release)","text":"<ul> <li>Bug fixes:<ul> <li>Fixed output culture option ignored. #449</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0160-b2003022-pre-release","title":"v0.16.0-B2003022 (pre-release)","text":"<ul> <li>General improvements:<ul> <li>Added configuration option <code>Output.Culture</code> for setting culture. #442</li> <li>Improved handling of fields to allow the input object to be referenced with <code>.</code>. #437</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed numeric comparison assertion with non-int types. #436</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0150","title":"v0.15.0","text":"<p>What's changed since v0.14.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>-ResultVariable</code> to store results from Assert-PSRule into a variable. #412</li> </ul> </li> <li>General improvements:<ul> <li>Added recommendation to failure message of NUnit results. #421</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling of <code>v</code> in field value with <code>$Assert.Version</code>. #429</li> <li>Fixed handling of warning action preference with <code>Assert-PSRule</code>. #428</li> <li>Fixed parent culture unwind with POSIX. #414</li> <li>Fixed output of warning with <code>Assert-PSRule</code>. #417</li> <li>Fixed NUnit report to include a failure element when reason is not specified. #420</li> </ul> </li> </ul> <p>What's changed since pre-release v0.15.0-B2002031:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002031-pre-release","title":"v0.15.0-B2002031 (pre-release)","text":"<ul> <li>Fixed handling of <code>v</code> in field value with <code>$Assert.Version</code>. #429</li> <li>Fixed handling of warning action preference with <code>Assert-PSRule</code>. #428</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002019-pre-release","title":"v0.15.0-B2002019 (pre-release)","text":"<ul> <li>Added <code>-ResultVariable</code> to store results from Assert-PSRule into a variable. #412</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002012-pre-release","title":"v0.15.0-B2002012 (pre-release)","text":"<ul> <li>Fixed output of warning with <code>Assert-PSRule</code>. #417</li> <li>Fixed NUnit report to include a failure element when reason is not specified. #420</li> <li>Added recommendation to failure message of NUnit results. #421</li> </ul>"},{"location":"CHANGELOG-v0/#v0150-b2002005-pre-release","title":"v0.15.0-B2002005 (pre-release)","text":"<ul> <li>Fixed parent culture unwind with POSIX. #414</li> </ul>"},{"location":"CHANGELOG-v0/#v0140","title":"v0.14.0","text":"<p>What's changed since v0.13.0:</p> <ul> <li>Engine features:<ul> <li>Added support for qualified target names. #395<ul> <li>Added options <code>Binding.UseQualifiedName</code> and <code>Binding.NameSeparator</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added assertion method <code>HasJsonSchema</code> to check if a JSON schema is referenced. #398<ul> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Added file content helper for reading objects from files. #399<ul> <li>The method <code>GetContent</code> of <code>$PSRule</code> can be used to read files as objects.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Improved reporting on runtime errors in rule blocks. #239</li> <li>Improved NUnit results to include a failure message based on reported reasons. #404</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed wide formatting of rules with <code>Get-PSRule</code>. #407</li> <li>Fixed TargetName hash serialization for base types. #406</li> <li>Fixed output not generated with Assert-PSRule and Stop. #405</li> <li>Fixed NUnit results incorrectly reporting that the test had not executed. #403</li> </ul> </li> </ul> <p>What's changed since pre-release v0.14.0-B2002003:</p> <ul> <li>No additional changes</li> </ul>"},{"location":"CHANGELOG-v0/#v0140-b2002003-pre-release","title":"v0.14.0-B2002003 (pre-release)","text":"<ul> <li>Fixed wide formatting of rules with <code>Get-PSRule</code>. #407</li> <li>Fixed TargetName hash serialization for base types. #406</li> <li>Fixed output not generated with Assert-PSRule and Stop. #405</li> <li>Fixed NUnit results incorrectly reporting that the test had not executed. #403</li> <li>Improved NUnit results to include a failure message based on reported reasons. #404</li> <li>Improved reporting on runtime errors in rule blocks. #239</li> </ul>"},{"location":"CHANGELOG-v0/#v0140-b2001020-pre-release","title":"v0.14.0-B2001020 (pre-release)","text":"<ul> <li>Added support for qualified target names. #395<ul> <li>Added options <code>Binding.UseQualifiedName</code> and <code>Binding.NameSeparator</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added assertion method <code>HasJsonSchema</code> to check if a JSON schema is referenced. #398<ul> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Added file content helper for reading objects from files. #399<ul> <li>The method <code>GetContent</code> of <code>$PSRule</code> can be used to read files as objects.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130","title":"v0.13.0","text":"<p>What's changed since v0.12.0:</p> <ul> <li>Engine features:<ul> <li>Improvements to rule help and documentation. #382 #316<ul> <li>Added links and notes sections to help.</li> <li>Added <code>-Full</code> switch to <code>Get-PSRuleHelp</code> to display links and notes sections.</li> <li>Added support for using a parent culture in rule help.</li> <li>Rule help will use parent culture when a more specific culture is not available.</li> </ul> </li> <li>Added input format for reading PowerShell data <code>.psd1</code> files. #368<ul> <li><code>PowerShellData</code> has been added to <code>Input.Format</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added custom rule data to results. #322<ul> <li><code>$PSRule.Data</code> can be used to set custom data during rule execution that is included in output.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> <li>Improvements to assertion methods. #386 #374 #387 #344 #353 #357<ul> <li>Added support for assertion methods to be used within script pre-conditions.</li> <li>Added numeric comparison assertion helpers <code>Greater</code>, <code>GreaterOrEqual</code>, <code>Less</code> and <code>LessOrEqual</code>.</li> <li>Added semantic version assertion helper <code>Version</code>.</li> <li>Added string affix assertion helpers <code>StartsWith</code>, <code>EndsWith</code> and <code>Contains</code>.</li> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Improvements to output logging and formatting for <code>Assert-PSRule</code>.<ul> <li>Formatting now includes errors and warnings using style.</li> <li>Added PSRule banner with module information.</li> <li>Added rule success summary.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added aliases for <code>-OutputFormat</code> (<code>-o</code>) and <code>-Module</code> (<code>-m</code>) parameters. #384</li> <li>Added <code>WithReason</code> to append/ replace reasons from assertion result. #354</li> <li>Added configuration helper for strings arrays. #363</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed JSON de-serialization fails with single object. #379</li> <li>Fixed stack overflow when parsing malformed JSON. #380</li> </ul> </li> </ul> <p>What's changed since pre-release v0.13.0-B2001013:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b2001013-pre-release","title":"v0.13.0-B2001013 (pre-release)","text":"<ul> <li>Fixed JSON de-serialization fails with single object. #379</li> <li>Fixed stack overflow when parsing malformed JSON. #380</li> <li>Added rule documentation links and notes to help. #382<ul> <li>Added <code>-Full</code> switch to <code>Get-PSRuleHelp</code> to display links and notes sections.</li> </ul> </li> <li>Added aliases for <code>-OutputFormat</code> (<code>-o</code>) and <code>-Module</code> (<code>-m</code>) parameters. #384</li> <li>Improved numeric comparison assertion helpers to support strings. #387<ul> <li>Methods <code>Greater</code>, <code>GreaterOrEqual</code>, <code>Less</code> and <code>LessOrEqual</code> now also check string length.</li> </ul> </li> <li>Added support for assertion methods to be used within script pre-conditions. #386</li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912043-pre-release","title":"v0.13.0-B1912043 (pre-release)","text":"<ul> <li>Added input format for reading PowerShell data <code>.psd1</code> files. #368<ul> <li><code>PowerShellData</code> has been added to <code>Input.Format</code>.</li> <li>See <code>about_PSRule_Options</code> for details.</li> </ul> </li> <li>Added numeric comparison assertion helpers. #374<ul> <li>Added methods <code>Greater</code>, <code>GreaterOrEqual</code>, <code>Less</code> and <code>LessOrEqual</code>.</li> <li>See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912027-pre-release","title":"v0.13.0-B1912027 (pre-release)","text":"<ul> <li>Added configuration helper for strings arrays. #363</li> <li>Added support for using a parent culture in rule help. #316<ul> <li>Rule help will use parent culture when a more specific culture is not available.</li> </ul> </li> <li>Added custom rule data to results. #322<ul> <li><code>$PSRule.Data</code> can be used to set custom data during rule execution that is included in output.</li> <li>See <code>about_PSRule_Variables</code> for usage details.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912012-pre-release","title":"v0.13.0-B1912012 (pre-release)","text":"<ul> <li>Improves output logging and formatting for Assert-PSRule. #357<ul> <li>Formatting now includes errors and warnings using style.</li> <li>Added PSRule banner with module information.</li> <li>Added rule success summary.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0130-b1912005-pre-release","title":"v0.13.0-B1912005 (pre-release)","text":"<ul> <li>Added semantic version assertion helper <code>Version</code>. #344</li> <li>Added string affix assertion helpers. #353<ul> <li>Added methods <code>StartsWith</code>, <code>EndsWith</code> and <code>Contains</code>. See <code>about_PSRule_Assert</code> for usage details.</li> </ul> </li> <li>Added <code>WithReason</code> to append/ replace reasons from assertion result. #354</li> </ul>"},{"location":"CHANGELOG-v0/#v0120","title":"v0.12.0","text":"<p>What's changed since v0.11.0:</p> <ul> <li>Engine features:<ul> <li>Added <code>-All</code> option to <code>Exists</code> keyword. #331</li> <li>Added custom field binding. #321<ul> <li>Added new option <code>Binding.Field</code> available in baselines to configure binding.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added filtering for rules against a baseline with <code>Get-PSRule</code>. #345</li> <li>Added parameter alias <code>-f</code> for <code>-InputPath</code>. #340<ul> <li><code>-f</code> was added to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code> cmdlets.</li> </ul> </li> </ul> </li> <li>Important change: Added <code>$PSRule</code> generic context variable. #341<ul> <li>Deprecated <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> properties on <code>$Rule</code>.</li> <li>Use <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$PSRule</code> instead.</li> <li>Properties <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$Rule</code> will be removed in the future.</li> <li>Going forward <code>$Rule</code> will only contain properties that relate to the current rule context.</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed key has already been added for default baseline. #349</li> <li>Fixed multiple value tag filtering. #346</li> <li>Fixed TargetType fall back to type name. #339</li> <li>Fixed NUnit serialization issue for unprocessed rules. #332</li> </ul> </li> </ul> <p>What's changed since pre-release v0.12.0-B1912007:</p> <ul> <li>Fixed key has already been added for default baseline. #349</li> </ul>"},{"location":"CHANGELOG-v0/#v0120-b1912007-pre-release","title":"v0.12.0-B1912007 (pre-release)","text":"<ul> <li>Fixed multiple value tag filtering. #346</li> <li>Added filtering for rules against a baseline with <code>Get-PSRule</code>. #345</li> </ul>"},{"location":"CHANGELOG-v0/#v0120-b1912002-pre-release","title":"v0.12.0-B1912002 (pre-release)","text":"<ul> <li>Fixed TargetType fall back to type name. #339</li> <li>Added custom field binding. #321<ul> <li>Added new option <code>Binding.Field</code> available in baselines to configure binding.</li> </ul> </li> <li>Added parameter alias <code>-f</code> for <code>-InputPath</code>. #340<ul> <li><code>-f</code> was added to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code> cmdlets.</li> </ul> </li> <li>Important change: Added <code>$PSRule</code> generic context variable. #341<ul> <li>Deprecated <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> properties on <code>$Rule</code>.</li> <li>Use <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$PSRule</code> instead.</li> <li>Properties <code>TargetName</code>, <code>TargetType</code> and <code>TargetObject</code> on <code>$Rule</code> will be removed in the future.</li> <li>Going forward <code>$Rule</code> will only contain properties that relate to the current rule context.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0120-b1911013-pre-release","title":"v0.12.0-B1911013 (pre-release)","text":"<ul> <li>Fixed NUnit serialization issue for unprocessed rules. #332</li> <li>Added <code>-All</code> option to <code>Exists</code> keyword. #331</li> </ul>"},{"location":"CHANGELOG-v0/#v0110","title":"v0.11.0","text":"<p>What's changed since v0.10.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>-TargetType</code> parameter to filter input objects by target type. #176<ul> <li>This parameter applies to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code>.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed null reference exception when bound property is null. #323</li> <li>Fixed missing <code>Markdown</code> input format in options schema. #315</li> </ul> </li> <li>Breaking change: Unprocessed object results are not returned from <code>Test-PSRuleTarget</code> by default. #318<ul> <li>Previously unprocessed objects returned <code>$True</code>, now unprocessed objects return no result.</li> <li>Use <code>-Outcome All</code> to return <code>$True</code> for unprocessed objects the same as &lt;= v0.10.0.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.11.0-B1911002:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0110-b1911002-pre-release","title":"v0.11.0-B1911002 (pre-release)","text":"<ul> <li>Fixed null reference exception when bound property is null. #323</li> </ul>"},{"location":"CHANGELOG-v0/#v0110-b1910014-pre-release","title":"v0.11.0-B1910014 (pre-release)","text":"<ul> <li>Fixed missing <code>Markdown</code> input format in options schema. #315</li> <li>Added <code>-TargetType</code> parameter to filter input objects by target type. #176<ul> <li>This parameter applies to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> and <code>Test-PSRuleTarget</code>.</li> </ul> </li> <li>Breaking change: Unprocessed object results are not returned from <code>Test-PSRuleTarget</code> by default. #318<ul> <li>Previously unprocessed objects returned <code>$True</code>, now unprocessed objects return no result.</li> <li>Use <code>-Outcome All</code> to return <code>$True</code> for unprocessed objects the same as &lt;= v0.10.0.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0100","title":"v0.10.0","text":"<p>What's changed since v0.9.0:</p> <ul> <li>General improvements:<ul> <li>Added source note properties to input objects read from disk with <code>-InputPath</code>. #302</li> </ul> </li> <li>Engine features:<ul> <li>Added assertion helper for checking field default value. #289</li> <li>Added dependency <code>DependsOn</code> information to results from <code>Get-PSRule</code>. #210<ul> <li>To include dependencies that would normally be filtered out use <code>-IncludeDependencies</code>.</li> </ul> </li> <li>Added input format for reading markdown front matter. #301<ul> <li>Markdown front matter is deserialized and evaluated as an object.</li> </ul> </li> <li>Added <code>Assert-PSRule</code> cmdlet to improve integration into CI processes. #290<ul> <li>Added <code>Output.Style</code> option to support output in the following styles:<ul> <li>Client/ Plain - Output returns easy to read log of rule pass/ fail.</li> <li>Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.</li> <li>GitHub Actions - Reports rule failures as errors collected by GitHub Actions.</li> </ul> </li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fix <code>Get-PSRuleHelp</code> -Online in constrained language mode. #296</li> </ul> </li> <li>Breaking change: Removed previously deprecated alias <code>Hint</code> for <code>Recommend</code>. #165<ul> <li>Use the <code>Recommend</code> keyword instead.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.10.0-B1910036:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v0100-b1910036-pre-release","title":"v0.10.0-B1910036 (pre-release)","text":"<ul> <li>Added dependency <code>DependsOn</code> information to results from <code>Get-PSRule</code>. #210<ul> <li>To include dependencies that would normally be filtered out use <code>-IncludeDependencies</code>.</li> </ul> </li> <li>Added input format for reading markdown front matter. #301<ul> <li>Markdown front matter is deserialized and evaluated as an object.</li> </ul> </li> <li>Added source note properties to input objects read from disk with <code>-InputPath</code>. #302</li> <li>Breaking change: Removed previously deprecated alias <code>Hint</code> for <code>Recommend</code>. #165<ul> <li>Use the <code>Recommend</code> keyword instead.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0100-b1910025-pre-release","title":"v0.10.0-B1910025 (pre-release)","text":"<ul> <li>Fix <code>Get-PSRuleHelp</code> -Online in constrained language mode. #296</li> <li>Added <code>Assert-PSRule</code> cmdlet to improve integration into CI processes. #290<ul> <li>Added <code>Output.Style</code> option to support output in the following styles:<ul> <li>Client/ Plain - Output returns easy to read log of rule pass/ fail.</li> <li>Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.</li> <li>GitHub Actions - Reports rule failures as errors collected by GitHub Actions.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v0100-b1910011-pre-release","title":"v0.10.0-B1910011 (pre-release)","text":"<ul> <li>Added assertion helper for checking field default value. #289</li> </ul>"},{"location":"CHANGELOG-v0/#v090","title":"v0.9.0","text":"<p>What's changed since v0.8.0:</p> <ul> <li>General improvements:<ul> <li>Improve feedback of parsing errors. #185</li> <li>Updated <code>Get-PSRuleHelp</code> to include help within the current path by default. #197</li> </ul> </li> <li>Engine features:<ul> <li>Added support for a wildcard match using the <code>Within</code> keyword. #272</li> <li>Added rule info display name. #276</li> <li>Added support for matching an array of tag values. #282</li> <li>Added named baselines. Now baselines are a separate resource that can be individually used.<ul> <li>Baselines can be packaged within module.</li> <li>Modules can specify a default baseline in module manifest.</li> <li>Target binding options (<code>Binding</code>) are now part of baselines.</li> <li>See about_PSRule_Baseline for more information.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fix can not serialize nested System.IO.DirectoryInfo property. #281</li> <li>Fix ModuleName not displayed in Get-PSRuleHelp list. #275</li> <li>Fix outcome reported when error or exception is raised. #211</li> </ul> </li> <li>Breaking change: Baseline improvements, fundamentally changes how baselines work. #274<ul> <li>Previously, baselines were specified as workspace options.</li> <li>The previous <code>baseline</code> options property has been renamed to <code>rule</code>.</li> <li>The previous <code>configuration</code> property is now a top level option.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.9.0-B190905:</p> <ul> <li>No additional changes</li> </ul>"},{"location":"CHANGELOG-v0/#v090-b190905-pre-release","title":"v0.9.0-B190905 (pre-release)","text":"<ul> <li>Added support for matching an array of tag values. #282</li> <li>Updated <code>Get-PSRuleHelp</code> to include help within the current path by default. #197</li> <li>Fix can not serialize nested System.IO.DirectoryInfo property. #281</li> <li>Fix export of <code>Like</code> parameter for <code>Within</code> keyword. #279</li> <li>Breaking change: Added named baselines. This changes how baselines work. #274<ul> <li>Previously, baselines were specified as workspace options.</li> <li>Now, baselines are a separate resource that can be individually used. Additionally:<ul> <li>Baselines can be packaged within module.</li> <li>Modules can specify a default baseline in module manifest.</li> <li>Target binding options (<code>Binding</code>) are now part of baselines.</li> </ul> </li> <li>The previous <code>baseline</code> options property has been renamed to <code>rule</code>.</li> <li>The previous <code>configuration</code> property is now a top level option.</li> <li>See about_PSRule_Baseline for more information.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v090-b190819-pre-release","title":"v0.9.0-B190819 (pre-release)","text":"<ul> <li>Added support for a wildcard match using the <code>Within</code> keyword. #272</li> <li>Added rule info display name. #276</li> <li>Fix ModuleName not displayed in Get-PSRuleHelp list. #275</li> </ul>"},{"location":"CHANGELOG-v0/#v090-b190810-pre-release","title":"v0.9.0-B190810 (pre-release)","text":"<ul> <li>Improve feedback of parsing errors. #185</li> <li>Fix outcome reported when error or exception is raised. #211</li> </ul>"},{"location":"CHANGELOG-v0/#v080","title":"v0.8.0","text":"<p>What's changed since v0.7.0:</p> <ul> <li>General improvements:<ul> <li>PSRule options are now displayed as YAML instead of a complex object. #233</li> <li>Add detection for improper keyword use. #203</li> <li>Automatically load rule modules. #218</li> <li>Added support for debug messages and <code>Write-Debug</code> in rule definitions. #146</li> <li>Added <code>Logging.LimitDebug</code> and <code>Logging.LimitVerbose</code> options to limit logging to named scopes. #235</li> </ul> </li> <li>Engine features:<ul> <li>Added per object reason for failing rules. #200<ul> <li>Keywords <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> automatically add a reason when they fail.</li> <li>Custom reason can be set for keywords <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> with <code>-Reason</code>.</li> <li>Added <code>Reason</code> keyword to add to reason for custom logic.</li> <li>Added wide output display for <code>Invoke-PSRule</code> which include the reason why rule failed.<ul> <li>To use wide output use the <code>-OutputFormat Wide</code> parameter.</li> </ul> </li> <li>Renamed <code>-Message</code> parameter to <code>-Text</code> on the <code>Recommend</code> keyword.<ul> <li>The <code>-Message</code> is an alias of <code>-Text</code> and will be deprecated in the future.</li> </ul> </li> </ul> </li> <li>Added assertion helper <code>$Assert</code> for extensibility. #250<ul> <li>Add built-in assertions for <code>HasField</code>, <code>HasFieldValue</code> and <code>NullOrEmpty</code>.</li> <li>Add JSON schema assertion method <code>JsonSchema</code>. #42</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fix rule synopsis comment capture. #214</li> <li>Fix YAML options file discovery issue in dotted directory. #232</li> <li>Fix comparison of wrapped types and null with <code>Within</code>. #237</li> </ul> </li> <li>Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217<ul> <li>Rule names have to be unique within the current execution path or within a module.<ul> <li>Previously rule names only had to be unique within a single file.</li> </ul> </li> <li>Previously the <code>filename.rule.ps1/RuleName</code> was required to reference rules across files.<ul> <li>This is no longer required because rule names are unique.</li> </ul> </li> <li>You can reference a rule from a loaded module by using the syntax <code>ModuleName\\RuleName</code>.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.8.0-B190806:</p> <ul> <li>Fix export of assertion helper variable <code>$Assert</code>. #262</li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190806-pre-release","title":"v0.8.0-B190806 (pre-release)","text":"<ul> <li>Fix module reloading with different versions. #254</li> <li>Fix not finding rules in current path by default. #256</li> <li>Fix rule synopsis comment capture. #214</li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190742-pre-release","title":"v0.8.0-B190742 (pre-release)","text":"<ul> <li>Fix inconsistent handling of <code>$PWD</code>. #249</li> <li>Add detection for improper keyword use. #203</li> <li>Automatically load rule modules. #218</li> <li>Added assertion helper <code>$Assert</code> for extensibility. #250<ul> <li>Add built-in assertions for <code>HasField</code>, <code>HasFieldValue</code> and <code>NullOrEmpty</code>.</li> <li>Add JSON schema assertion method <code>JsonSchema</code>. #42</li> </ul> </li> <li>Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217<ul> <li>Rule names have to be unique within the current execution path or within a module.<ul> <li>Previously rule names only had to be unique within a single file.</li> </ul> </li> <li>Previously the <code>filename.rule.ps1/RuleName</code> was required to reference rules across files.<ul> <li>This is no longer required because rule names are unique.</li> </ul> </li> <li>You can reference a rule from a loaded module by using the syntax <code>ModuleName\\RuleName</code>.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190716-pre-release","title":"v0.8.0-B190716 (pre-release)","text":"<ul> <li>Added per object reason for failing rules. #200<ul> <li>The keywords <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> automatically add a reason when they fail.</li> <li>Added <code>-Reason</code> parameter to <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> keywords to allow a custom reason to be set.</li> <li>Added <code>Reason</code> keyword to add to reason for custom logic.</li> <li>Added wide output display for <code>Invoke-PSRule</code> which include the reason why rule failed.<ul> <li>To use wide output use the <code>-OutputFormat Wide</code> parameter.</li> </ul> </li> <li>Renamed <code>-Message</code> parameter to <code>-Text</code> on the <code>Recommend</code> keyword.<ul> <li>The <code>-Message</code> is an alias of <code>-Text</code> and will be deprecated in the future.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v080-b190708-pre-release","title":"v0.8.0-B190708 (pre-release)","text":"<ul> <li>Fix YAML options file discovery issue in dotted directory. #232</li> <li>Fix comparison of wrapped types and null with <code>Within</code>. #237</li> <li>PSRule options are now displayed as YAML instead of a complex object. #233</li> <li>Added support for debug messages and <code>Write-Debug</code> in rule definitions. #146</li> <li>Added <code>Logging.LimitDebug</code> and <code>Logging.LimitVerbose</code> options to limit logging to named scopes. #235</li> </ul>"},{"location":"CHANGELOG-v0/#v070","title":"v0.7.0","text":"<p>What's changed since v0.6.0:</p> <ul> <li>Fix reading nested arrays from JSON input. #223</li> <li>Fix comparison of non-string types with <code>Within</code>. #226</li> <li>Fix circular rule dependency issue. #190</li> <li>Fix rule <code>DependsOn</code> parameter allows null. #191</li> <li>Fix error message when attempting to use the rule keyword in a rule definition. #189</li> <li>Fix TargetName binding when TargetName or Name property is null. #202</li> <li>Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187 #224</li> <li>Include .ps1 files that are specified directly with <code>-Path</code>, instead of only .Rule.ps1 files. #182<ul> <li>Improved warning message displayed when no Rule.ps1 files are founds.</li> </ul> </li> <li>Added support for <code>Invoke-PSRule</code> to return CSV formatted results. #169<ul> <li>To generate CSV results use the <code>-OutputFormat Csv</code> parameter.</li> <li>Added <code>Output.Path</code> option to allow output to be saved directly to file.</li> <li>Added <code>Output.Encoding</code> option configure encoding used to write to file.</li> <li>By default, UTF-8 encoding without BOM is used.</li> <li><code>Invoke-PSRule</code> cmdlet also provides a parameter <code>-OutputPath</code> to write results to file.</li> </ul> </li> <li>Reordered cmdlet parameters to improve usage of frequently used parameters. #175<ul> <li><code>-Module</code> parameter will tab-complete with imported rule modules.</li> </ul> </li> <li>Added culture support for PowerShell informational messages. #158<ul> <li>A new <code>$LocalizedData</code> variable can be used within rule definitions.</li> </ul> </li> <li>Added <code>-Not</code> switch to <code>Within</code> and <code>Match</code> keywords to allow negative comparison. #208</li> <li>Improve discovery of rule tags. #209<ul> <li>Add wide format <code>-OutputFormat Wide</code> to <code>Get-PSRule</code> to allow output of rule tags.</li> </ul> </li> <li>Breaking change: Changed rule filtering by tag to be case-insensitive. #204<ul> <li>Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.</li> </ul> </li> <li>Breaking change: Rule time is recorded in milliseconds instead of seconds. #192</li> </ul> <p>What's changed since pre-release v0.7.0-B190664:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190664-pre-release","title":"v0.7.0-B190664 (pre-release)","text":"<ul> <li>Fix reading nested arrays from JSON input. #223</li> <li>Fix comparison of non-string types with <code>Within</code>. #226</li> <li>Improve handling of null rule result. #224</li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190652-pre-release","title":"v0.7.0-B190652 (pre-release)","text":"<ul> <li>Fix TargetName binding when TargetName or Name property is null. #202</li> <li>Add culture support for PowerShell informational messages. #158<ul> <li>A new <code>$LocalizedData</code> variable can be used within rule definitions.</li> </ul> </li> <li>Add <code>-Not</code> switch to <code>Within</code> and <code>Match</code> keywords to allow negative comparison. #208</li> <li>Improve discovery of rule tags. #209<ul> <li>Add wide format <code>-OutputFormat Wide</code> to <code>Get-PSRule</code> to allow output of rule tags.</li> </ul> </li> <li>Breaking change: Change rule filtering by tag to be case-insensitive. #204<ul> <li>Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190633-pre-release","title":"v0.7.0-B190633 (pre-release)","text":"<ul> <li>Fix circular rule dependency issue. #190</li> <li>Fix rule <code>DependsOn</code> parameter allows null. #191</li> <li>Fix error message when attempting to use the rule keyword in a rule definition. #189</li> <li>Breaking change: Rule time is recorded in milliseconds instead of seconds. #192</li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190624-pre-release","title":"v0.7.0-B190624 (pre-release)","text":"<ul> <li>Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187</li> <li>Include .ps1 files that are specified directly with <code>-Path</code>, instead of only .rule.ps1 files. #182<ul> <li>Improved warning message displayed when no Rule.ps1 files are founds.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v070-b190613-pre-release","title":"v0.7.0-B190613 (pre-release)","text":"<ul> <li>Added support for <code>Invoke-PSRule</code> to return CSV formatted results. #169<ul> <li>To generate CSV results use the <code>-OutputFormat Csv</code> parameter.</li> <li>Added <code>Output.Path</code> option to allow output to be saved directly to file.</li> <li>Added <code>Output.Encoding</code> option configure encoding used to write to file.</li> <li>By default, UTF-8 encoding without BOM is used.</li> <li><code>Invoke-PSRule</code> cmdlet also provides a parameter <code>-OutputPath</code> to write results to file.</li> </ul> </li> <li>Reordered cmdlet parameters to improve usage of frequently used parameters. #175<ul> <li><code>-Module</code> parameter will tab-complete with imported rule modules.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v060","title":"v0.6.0","text":"<p>What's changed since v0.5.0:</p> <ul> <li>Fix operation is not supported on this platform failure. #152</li> <li>Fix FullName cannot be found on this object error. #149</li> <li>Fix discovery of rules within paths that contain spaces fails. #168</li> <li>Added rule documentation, which allows additional rule information to be stored in markdown files. #157<ul> <li>Rule documentation also adds culture support. #18</li> <li>Rule documentation can be accessed like help with the <code>Get-PSRuleHelp</code> cmdlet.</li> </ul> </li> <li>Added annotations, which are non-indexed metadata stored in rule documentation. #148<ul> <li>Annotations can contain a link to online version of the documentation. #147</li> </ul> </li> <li>Important change: Changed <code>Hint</code> keyword to <code>Recommend</code> to align with rule documentation. #165<ul> <li>Use of <code>Hint</code> keyword is deprecated and will be removed in a future release. Currently <code>Hint</code> is aliased to <code>Recommend</code> for compatibility.</li> </ul> </li> <li>Breaking change: Changed rule properties to align with rule documentation. #164<ul> <li>Rule <code>Synopsis</code>, is a brief summary of the rule and <code>Description</code> is a detailed purpose of the rule.</li> <li><code>Description:</code> metadata keyword used in comment help is now <code>Synopsis:</code>, use of <code>Description:</code> will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.</li> <li>Output property <code>Message</code> on rule results is now <code>Recommendation</code>.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.6.0-B190627:</p> <ul> <li>Fix discovery of rules within paths that contain spaces fails. #168</li> <li>Fix exporting of <code>Recommend</code> keyword and <code>Hint</code> alias. #171</li> </ul>"},{"location":"CHANGELOG-v0/#v060-b190627-pre-release","title":"v0.6.0-B190627 (pre-release)","text":"<ul> <li>Important change: Changed <code>Hint</code> keyword to <code>Recommend</code> to align with rule documentation. #165<ul> <li>Use of <code>Hint</code> keyword is deprecated and will be removed in a future release. Currently <code>Hint</code> is aliased to <code>Recommend</code> for compatibility.</li> </ul> </li> <li>Breaking change: Changed rule properties to align with rule documentation. #164<ul> <li>Rule <code>Synopsis</code>, is a brief summary of the rule and <code>Description</code> is a detailed purpose of the rule.</li> <li><code>Description:</code> metadata keyword used in comment help is now <code>Synopsis:</code>, use of <code>Description:</code> will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.</li> <li>Output property <code>Message</code> on rule results is now <code>Recommendation</code>.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v060-b190614-pre-release","title":"v0.6.0-B190614 (pre-release)","text":"<ul> <li>Added rule documentation, which allows additional rule information to be stored in markdown files. #157<ul> <li>Rule documentation also adds culture support. #18</li> <li>Rule documentation can be accessed like help with the <code>Get-PSRuleHelp</code> cmdlet.</li> </ul> </li> <li>Added annotations, which are non-indexed metadata stored in rule documentation. #148<ul> <li>Annotations can contain a link to online version of the documentation. #147</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v060-b190514-pre-release","title":"v0.6.0-B190514 (pre-release)","text":"<ul> <li>Fix operation is not supported on this platform failure. #152</li> <li>Fix FullName cannot be found on this object error. #149</li> </ul>"},{"location":"CHANGELOG-v0/#v050","title":"v0.5.0","text":"<p>What's changed since v0.4.0:</p> <ul> <li>Fix PSRule options schema usage of additionalProperties. #136</li> <li>Fix null reference exception when traversing null field. #123</li> <li>Fix missing help topics for options and variables. #125</li> <li>Improved handling of default YAML options file. #137</li> <li>Added support for <code>Invoke-PSRule</code> to return NUnit3 formatted results. #129<ul> <li>To generate NUnit3 results use the <code>-OutputFormat NUnit3</code> parameter.</li> </ul> </li> <li>Added <code>Set-PSRuleOption</code> cmdlet to configure YAML options file. #135</li> <li>Added parameters to New-PSRuleOption to configure common options. #134<ul> <li>Additional parameters are an alternative to using a <code>-Option</code> hashtable.</li> </ul> </li> </ul> <p>What's changed since pre-release v0.5.0-B190423:</p> <ul> <li>Fix schema conformance of <code>-OutputFormat NUnit3</code> to NUnit report schema. #141</li> <li>Fix PSRule options schema usage of additionalProperties. #136</li> </ul>"},{"location":"CHANGELOG-v0/#v050-b190423-pre-release","title":"v0.5.0-B190423 (pre-release)","text":"<ul> <li>Added support for <code>Invoke-PSRule</code> to return NUnit3 formatted results. #129<ul> <li>To generate NUnit3 results use the <code>-OutputFormat NUnit3</code> parameter.</li> </ul> </li> <li>Added <code>Set-PSRuleOption</code> cmdlet to configure YAML options file. #135</li> <li>Added parameters to New-PSRuleOption to configure common options. #134<ul> <li>Additional parameters are an alternative to using a <code>-Option</code> hashtable.</li> </ul> </li> <li>Improved handling of default YAML options file. #137</li> </ul>"},{"location":"CHANGELOG-v0/#v050-b190405-pre-release","title":"v0.5.0-B190405 (pre-release)","text":"<ul> <li>Fix null reference exception when traversing null field. #123</li> <li>Fix missing help topics for options and variables. #125</li> </ul>"},{"location":"CHANGELOG-v0/#v040","title":"v0.4.0","text":"<p>What's changed since v0.3.0:</p> <ul> <li>Fix incorrect JSON de-serialization. #109 #111</li> <li>Added support for using <code>-InputPath</code> instead of using <code>-InputObject</code> to handle serialized objects. #106<ul> <li><code>-Format</code> is automatically detected for <code>.yaml</code>, <code>.yml</code> and <code>.json</code> file extensions.</li> </ul> </li> <li>Added <code>-OutputFormat</code> parameter to serialize output from <code>Invoke-PSRule</code> as YAML or JSON. #29</li> <li>Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97</li> <li>Breaking change: Deprecated usage of the <code>-TargetName</code> parameter on the <code>Hint</code> keyword has been removed. #81</li> </ul> <p>What's changed since pre-release v0.4.0-B190328:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v040-b190328-pre-release","title":"v0.4.0-B190328 (pre-release)","text":"<ul> <li>Fix summary is not correctly serialized with JSON or YAML output format. #116</li> <li>Fix missing properties on serialized YAML output. #115</li> <li>Fix incorrect property name case of YAML serialized results. #114</li> </ul>"},{"location":"CHANGELOG-v0/#v040-b190320-pre-release","title":"v0.4.0-B190320 (pre-release)","text":"<ul> <li>Fix incorrect JSON de-serialization of nested arrays. #109</li> <li>Fix incorrect JSON de-serialization of non-object arrays. #111</li> </ul>"},{"location":"CHANGELOG-v0/#v040-b190311-pre-release","title":"v0.4.0-B190311 (pre-release)","text":"<ul> <li>Added support for using <code>-InputPath</code> instead of using <code>-InputObject</code> to handle serialized objects. #106<ul> <li><code>-Format</code> is automatically detected for <code>.yaml</code>, <code>.yml</code> and <code>.json</code> file extensions.</li> </ul> </li> <li>Added <code>-OutputFormat</code> parameter to serialize output from <code>Invoke-PSRule</code>. #29</li> <li>Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97</li> <li>Breaking change: Deprecated usage of the <code>-TargetName</code> parameter on the <code>Hint</code> keyword has been removed. #81</li> </ul>"},{"location":"CHANGELOG-v0/#v030","title":"v0.3.0","text":"<p>What's changed since v0.2.0:</p> <ul> <li>Added support for pipelining with <code>Exists</code>, <code>Within</code>, <code>Match</code> and <code>TypeOf</code> keywords #90</li> <li>Added support for packaging rules in modules #16</li> <li>Import objects from YAML or JSON format #75<ul> <li>Added support for input de-serialization from FileInfo objects #95</li> </ul> </li> <li>Support nested TargetObjects #77</li> <li>Export variables to improve authoring experience #83</li> <li>Binding improvements:<ul> <li>Added object type binding and dynamic filtering for rules #82</li> <li>Added support for indexed and quoted field names #86</li> <li>Added support for case-sensitive binding operations #87<ul> <li>Binding ignores case by default. Set option <code>Binding.CaseSensitive</code> to <code>true</code> to enable case-sensitivity.</li> </ul> </li> <li>Support TargetName binding of nested properties #71</li> </ul> </li> <li>Added online help links to keywords #72</li> <li>Added schema for PSRule options #74</li> <li>Important change: The <code>-TargetName</code> parameter of the <code>Hint</code> keyword has been deprecated #81<ul> <li><code>-TargetName</code> parameter not longer sets the pipeline object TargetName and generates a warning instead.</li> <li>The <code>-TargetName</code> will be completely removed in v0.4.0, at which time using the parameter will generate an error.</li> </ul> </li> <li>Breaking change: Changed parameter alias for <code>-Path</code> from <code>-f</code> to <code>-p</code> #99</li> </ul> <p>What's changed since pre-release v0.3.0-B190231:</p> <ul> <li>Added support for input de-serialization from FileInfo objects #95</li> <li>Breaking change: Changed parameter alias for <code>-Path</code> from <code>-f</code> to <code>-p</code> #99</li> </ul>"},{"location":"CHANGELOG-v0/#v030-b190231-pre-release","title":"v0.3.0-B190231 (pre-release)","text":"<ul> <li>Added support for pipelining with <code>Exists</code>, <code>Within</code>, <code>Match</code> and <code>TypeOf</code> keywords #90</li> <li>Fix empty YAML object causes format de-serialize to fail #92</li> </ul>"},{"location":"CHANGELOG-v0/#v030-b190224-pre-release","title":"v0.3.0-B190224 (pre-release)","text":"<ul> <li>Export variables to improve authoring experience #83</li> <li>Added support for packaging rules in modules #16</li> <li>Added support for indexed and quoted field names #86</li> <li>Added object type binding and dynamic filtering for rules #82</li> <li>Added support for case-sensitive binding operations #87<ul> <li>Binding ignores case by default. Set option <code>Binding.CaseSensitive</code> to <code>true</code> to enable case-sensitivity.</li> </ul> </li> <li>Important change: The <code>-TargetName</code> parameter of the <code>Hint</code> keyword has been deprecated #81<ul> <li><code>-TargetName</code> parameter not longer sets the pipeline object TargetName and generates a warning instead.</li> <li>The <code>-TargetName</code> will be completely removed in v0.4.0, at which time using the parameter will generate an error.</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v030-b190208-pre-release","title":"v0.3.0-B190208 (pre-release)","text":"<ul> <li>Added online help links to keywords #72</li> <li>Added schema for PSRule options #74</li> <li>Import objects from YAML or JSON format #75</li> <li>Support TargetName binding of nested properties #71</li> <li>Support nested TargetObjects #77</li> </ul>"},{"location":"CHANGELOG-v0/#v020","title":"v0.2.0","text":"<p>What's changed since v0.1.0:</p> <ul> <li>Added support for cross-platform environments (Windows, Linux and macOS) #49</li> <li>Added support for nested field names with <code>Exists</code>, <code>Within</code> and <code>Match</code> keywords #60</li> <li>Added support for rule configuration using baselines #17</li> <li>Use rule description when hint message not set #61</li> <li>Allow objects to be suppressed by TargetName for individual rules #13</li> <li>Allow binding of TargetName to custom property #44</li> <li>Custom functions can be used to bind TargetName #44</li> <li>Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44</li> <li>Added <code>Test-PSRuleTarget</code> command to return an overall <code>$True</code> or <code>$False</code> after evaluating rules for an object #30</li> <li>Improve reporting of inconclusive results and objects that are not processed by any rule #46<ul> <li>Inconclusive results and objects not processed will return a warning by default.</li> </ul> </li> <li>Fix propagation of informational messages to host from rule scripts and definitions #48</li> <li>Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53</li> <li>Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54</li> </ul> <p>What's changed since pre-release v0.2.0-B190121:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v0/#v020-b190121-pre-release","title":"v0.2.0-B190121 (pre-release)","text":"<ul> <li>Added support for nested field names with <code>Exists</code>, <code>Within</code> and <code>Match</code> keywords #60</li> <li>Added support for rule configuration using baselines #17</li> <li>Use rule description when hint message not set #61</li> </ul>"},{"location":"CHANGELOG-v0/#v020-b190113-pre-release","title":"v0.2.0-B190113 (pre-release)","text":"<ul> <li>Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53</li> <li>Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54</li> <li>Breaking change: Renamed <code>Test-PSRule</code> cmdlet to <code>Test-PSRuleTarget</code> which aligns more closely to the verb-noun naming standard #57</li> </ul>"},{"location":"CHANGELOG-v0/#v020-b190105-pre-release","title":"v0.2.0-B190105 (pre-release)","text":"<ul> <li>Allow objects to be suppressed by TargetName for individual rules #13</li> <li>Allow binding of TargetName to custom property #44</li> <li>Custom functions can be used to bind TargetName #44</li> <li>Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44</li> <li>Added <code>Test-PSRule</code> command to return an overall <code>$True</code> or <code>$False</code> after evaluating rules for an object #30</li> <li>Improve reporting of inconclusive results and objects that are not processed by any rule #46<ul> <li>Inconclusive results and objects not processed will return a warning by default.</li> </ul> </li> <li>Fix propagation of informational messages to host from rule scripts and definitions #48</li> <li>Added support for cross-platform environments (Windows, Linux and macOS) #49</li> </ul>"},{"location":"CHANGELOG-v0/#v010","title":"v0.1.0","text":"<ul> <li>Initial release</li> </ul> <p>What's changed since pre-release v0.1.0-B181235:</p> <ul> <li>Fix outcome filtering of summary results #33</li> <li>Fix target object counter in verbose logging #35</li> <li>Fix hashtable keys should be handled as fields #36</li> </ul>"},{"location":"CHANGELOG-v0/#v010-b181235-pre-release","title":"v0.1.0-B181235 (pre-release)","text":"<ul> <li>RuleId and RuleName are now independent. Rules are created with a name, and the RuleId is generated based on rule name and file name<ul> <li>Rules with the same name can exist and be cross linked with DependsOn, as long a the script file name is different</li> </ul> </li> <li>Added <code>-Not</code> to <code>Exists</code> keyword</li> <li>Improved verbose logging of <code>Exists</code>, <code>AllOf</code>, <code>AnyOf</code> keywords and core engine</li> <li>Breaking change: Renamed outcome filtering parameters to align to type name and increase clarity<ul> <li><code>Invoke-PSRule</code> has a <code>-Outcome</code> parameter instead of <code>-Status</code></li> <li><code>-Outcome</code> supports values of <code>Pass</code>, <code>Fail</code>, <code>Error</code>, <code>None</code>, <code>Processed</code> and <code>All</code></li> </ul> </li> </ul>"},{"location":"CHANGELOG-v0/#v010-b181222-pre-release","title":"v0.1.0-B181222 (pre-release)","text":"<ul> <li>Added rule tags to results to enable grouping and sorting #14</li> <li>Added support to check for rule tag existence. Use <code>*</code> for tag value on <code>-Tag</code> parameter with <code>Invoke-PSRule</code> and <code>Get-PSRule</code></li> <li>Added option to report rule summary using <code>-As</code> parameter of <code>Invoke-PSRule</code> #12</li> </ul>"},{"location":"CHANGELOG-v0/#v010-b181212-pre-release","title":"v0.1.0-B181212 (pre-release)","text":"<ul> <li>Initial pre-release.</li> </ul>"},{"location":"CHANGELOG-v1/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Important notes:</p> <ul> <li>YAML resources will require an <code>apiVersion</code> from PSRule v2. #648</li> <li>Setting the default module baseline requires a module configuration from PSRule v2. #809</li> <li>Resource names have naming restrictions introduced from PSRule v2. #1012</li> </ul> <p>Attention</p> <p>PSRule v1 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.</p>"},{"location":"CHANGELOG-v1/#v1111","title":"v1.11.1","text":"<p>What's changed since v1.11.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed broken documentation links. #980</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v1110","title":"v1.11.0","text":"<p>What's changed since v1.10.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>version</code> expression to check semantic version constraints. #861<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> <li>Added <code>hasDefault</code> expression to check field default value. #870<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>GetReason()</code> not returning results for a failed assertion. #874</li> </ul> </li> </ul> <p>What's changed since pre-release v1.11.0-B2112016:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v1110-b2112016-pre-release","title":"v1.11.0-B2112016 (pre-release)","text":"<p>What's changed since v1.10.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>version</code> expression to check semantic version constraints. #861<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> <li>Added <code>hasDefault</code> expression to check field default value. #870<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>GetReason()</code> not returning results for a failed assertion. #874</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v1100","title":"v1.10.0","text":"<p>What's changed since v1.9.0:</p> <ul> <li>General improvements:<ul> <li>Added JSON support for reading rules and selectors from pipeline. #857</li> <li>Added <code>HasSchema</code> expression to check the schema of an object. #860<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.SourceLink.GitHub to 1.1.1. #856</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>$Assert.HasJsonSchema</code> accepts empty value. #859</li> <li>Fixed module configuration is not loaded when case does not match. #864</li> </ul> </li> </ul> <p>What's changed since pre-release v1.10.0-B2112002:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v1100-b2112002-pre-release","title":"v1.10.0-B2112002 (pre-release)","text":"<p>What's changed since pre-release v1.10.0-B2111024:</p> <ul> <li>Bug fixes:<ul> <li>Fixed module configuration is not loaded when case does not match. #864</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v1100-b2111024-pre-release","title":"v1.10.0-B2111024 (pre-release)","text":"<p>What's changed since v1.9.0:</p> <ul> <li>General improvements:<ul> <li>Added JSON support for reading rules and selectors from pipeline. #857</li> <li>Added <code>HasSchema</code> expression to check the schema of an object. #860<ul> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.SourceLink.GitHub to 1.1.1. #856</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>$Assert.HasJsonSchema</code> accepts empty value. #859</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190","title":"v1.9.0","text":"<p>What's changed since v1.8.0:</p> <ul> <li>General improvements:<ul> <li>Added improvements to YAML output for <code>Get-PSRuleBaseline</code>. #829</li> <li>Added <code>-Initialize</code> convention block. #826<ul> <li>Use this block to perform any initialization that is required before any rules are run.</li> <li>This block is only run once instead of <code>-Begin</code> which is run once per object.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> <li>Allow lifetime services to be used. #827<ul> <li>Use <code>$PSRule.AddService</code> and <code>$PSRule.GetService</code> to add a service.</li> <li>Services allows a singleton instance to be used and shared across multiple rules.</li> <li>PSRule will automatically dispose the service when all rules have run.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> <li>Added <code>Export-PSRuleBaseline</code> cmdlet to export baseline. #622</li> <li>Added JSON output format for Baseline cmdlets. #839</li> <li>Allow downstream issues to be consumed. #843<ul> <li>Objects can be flagged with issues that have been generated externally.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Migrated default baseline to module configuration. #809<ul> <li>This enables configuration of the default baseline for a module with a module configuration.</li> <li>This depreciate configuring the default baseline within the module manifest.</li> <li>Modules using manifest configuration will start warning from v1.9.0.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added JSON support to read baselines from pipeline. #845</li> </ul> </li> <li>Engineering:<ul> <li>Bump System.Drawing.Common dependency to v6.0.0. #848</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed convention execution is out of order. #835</li> </ul> </li> </ul> <p>What's changed since pre-release v1.9.0-B2111024:</p> <ul> <li>Engineering:<ul> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v6.0.0. #851</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2111024-pre-release","title":"v1.9.0-B2111024 (pre-release)","text":"<p>What's changed since pre-release v1.9.0-B2111009:</p> <ul> <li>General improvements:<ul> <li>Allow downstream issues to be consumed. #843<ul> <li>Objects can be flagged with issues that have been generated externally.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Migrated default baseline to module configuration. #809<ul> <li>This enables configuration of the default baseline for a module with a module configuration.</li> <li>This depreciate configuring the default baseline within the module manifest.</li> <li>Modules using manifest configuration will start warning from v1.9.0.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added JSON support to read baselines from pipeline. #845</li> </ul> </li> <li>Engineering:<ul> <li>Bump System.Drawing.Common dependency to v6.0.0. #848</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2111009-pre-release","title":"v1.9.0-B2111009 (pre-release)","text":"<p>What's changed since pre-release v1.9.0-B2110027:</p> <ul> <li>General improvements:<ul> <li>Added JSON output format for Baseline cmdlets. #839</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed convention execution is out of order. #835</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2110027-pre-release","title":"v1.9.0-B2110027 (pre-release)","text":"<p>What's changed since pre-release v1.9.0-B2110015:</p> <ul> <li>General improvements:<ul> <li>Added <code>Export-PSRuleBaseline</code> cmdlet to export baseline. #622</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v190-b2110015-pre-release","title":"v1.9.0-B2110015 (pre-release)","text":"<p>What's changed since v1.8.0:</p> <ul> <li>General improvements:<ul> <li>Added improvements to YAML output for <code>Get-PSRuleBaseline</code>. #829</li> <li>Added <code>-Initialize</code> convention block. #826<ul> <li>Use this block to perform any initialization that is required before any rules are run.</li> <li>This block is only run once instead of <code>-Begin</code> which is run once per object.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> <li>Allow lifetime services to be used. #827<ul> <li>Use <code>$PSRule.AddService</code> and <code>$PSRule.GetService</code> to add a service.</li> <li>Services allows a singleton instance to be used and shared across multiple rules.</li> <li>PSRule will automatically dispose the service when all rules have run.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180","title":"v1.8.0","text":"<p>What's changed since v1.7.2:</p> <ul> <li>General improvements:<ul> <li>Added YAML output format support for <code>Get-PSRuleBaseline</code>. #326</li> <li>Added YAML/JSON output format support for <code>Get-PSRule</code>. #128</li> <li>Added <code>Output.JsonIndent</code> option for JSON output format. #817</li> <li>Added assertion helpers and expressions for improving intersection checks. #795<ul> <li>Added <code>Count</code> to determine of the field has a specific number of elements.</li> <li>Added <code>SetOf</code> to determine if a collection is another collection.</li> <li>Added <code>Subset</code> to determine if a collection is includes another collection.</li> <li>See about_PSRule_Assert and about_PSRule_Expressions for details.</li> </ul> </li> <li>Added support for conditional reason messages with <code>ReasonIf</code>. #804<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for <code>type</code> and <code>name</code> expression properties. #810<ul> <li>Use <code>type</code> to compare the bound type of the current object.</li> <li>Use <code>name</code> to compare the bound name of the current object.</li> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Migration of Pester v4 tests to Pester v5. #478</li> </ul> </li> </ul> <p>What's changed since pre-release v1.8.0-B2110030:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2110030-pre-release","title":"v1.8.0-B2110030 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2110020:</p> <ul> <li>General improvements:<ul> <li>Added <code>Output.JsonIndent</code> option for JSON output format. #817</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2110020-pre-release","title":"v1.8.0-B2110020 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2110006:</p> <ul> <li>General improvements:<ul> <li>Added YAML/JSON output format support for <code>Get-PSRule</code>. #128</li> </ul> </li> <li>Engineering:<ul> <li>Migration of Pester v4 tests to Pester v5. #478</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2110006-pre-release","title":"v1.8.0-B2110006 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2109022:</p> <ul> <li>General improvements:<ul> <li>Added YAML output format support for <code>Get-PSRuleBaseline</code>. #326</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2109022-pre-release","title":"v1.8.0-B2109022 (pre-release)","text":"<p>What's changed since pre-release v1.8.0-B2109015:</p> <ul> <li>General improvements:<ul> <li>Added support for conditional reason messages with <code>ReasonIf</code>. #804<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for <code>type</code> and <code>name</code> expression properties. #810<ul> <li>Use <code>type</code> to compare the bound type of the current object.</li> <li>Use <code>name</code> to compare the bound name of the current object.</li> <li>See about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v180-b2109015-pre-release","title":"v1.8.0-B2109015 (pre-release)","text":"<p>What's changed since v1.7.2:</p> <ul> <li>General improvements:<ul> <li>Added assertion helpers and expressions for improving intersection checks. #795<ul> <li>Added <code>Count</code> to determine of the field has a specific number of elements.</li> <li>Added <code>SetOf</code> to determine if a collection is another collection.</li> <li>Added <code>Subset</code> to determine if a collection is includes another collection.</li> <li>See about_PSRule_Assert and about_PSRule_Expressions for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v172","title":"v1.7.2","text":"<p>What's changed since v1.7.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed <code>Get-PSRuleBaseline</code> does not return any results from module. #801</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v171","title":"v1.7.1","text":"<p>What's changed since v1.7.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed ResourceTags does not contain a method named ToHashtable. #798</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170","title":"v1.7.0","text":"<p>What's changed since v1.6.0:</p> <ul> <li>Engine features:<ul> <li>Added support for generating badges from rule results. #623<ul> <li>Standard or custom badges can be generated using a convention and the badge API.</li> <li>See about_PSRule_Badges for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Rule results now include a run ID or each run. #774<ul> <li>Run ID is returned in <code>Assert-PSRule</code> output at the end of each run by default.</li> <li>By default a unique <code>runId</code> is generated when the rule is run.</li> <li>The <code>Output.Footer</code>option was added to configure the output footer.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Automatically exclude common repository files from input files. #721<ul> <li>Added <code>Input.IgnoreRepositoryCommon</code> option to change default behavior.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added aggregation assertion methods for <code>AnyOf</code> and <code>AllOf</code>. #776<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Allow baselines to include local rules. #756<ul> <li>The <code>Rule.IncludeLocal</code>option was automatically include local/ standalone rules not in a module.</li> <li>This option is useful when you want to include local rules not included in a baseline.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed configuration array deserializes as dictionary from YAML options. #779</li> </ul> </li> </ul> <p>What's changed since pre-release v1.7.0-B2109002:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2109002-pre-release","title":"v1.7.0-B2109002 (pre-release)","text":"<p>What's changed since pre-release v1.7.0-B2108032:</p> <ul> <li>General improvements:<ul> <li>Allow baselines to include local rules. #756<ul> <li>The <code>Rule.IncludeLocal</code>option was automatically include local/ standalone rules not in a module.</li> <li>This option is useful when you want to include local rules not included in a baseline.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2108032-pre-release","title":"v1.7.0-B2108032 (pre-release)","text":"<p>What's changed since pre-release v1.7.0-B2108021:</p> <ul> <li>Engine features:<ul> <li>Added support for generating badges from rule results. #623<ul> <li>Standard or custom badges can be generated using a convention and the badge API.</li> <li>See about_PSRule_Badges for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Rule results now include a run ID or each run. #774<ul> <li>Run ID is returned in <code>Assert-PSRule</code> output at the end of each run by default.</li> <li>By default a unique <code>runId</code> is generated when the rule is run.</li> <li>The <code>Output.Footer</code>option was added to configure the output footer.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2108021-pre-release","title":"v1.7.0-B2108021 (pre-release)","text":"<p>What's changed since pre-release v1.7.0-B2108016:</p> <ul> <li>Bug fixes:<ul> <li>Fixed configuration array deserializes as dictionary from YAML options. #779</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v170-b2108016-pre-release","title":"v1.7.0-B2108016 (pre-release)","text":"<p>What's changed since v1.6.0:</p> <ul> <li>General improvements:<ul> <li>Automatically exclude common repository files from input files. #721<ul> <li>Added <code>Input.IgnoreRepositoryCommon</code> option to change default behavior.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added aggregation assertion methods for <code>AnyOf</code> and <code>AllOf</code>. #776<ul> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v161","title":"v1.6.1","text":"<p>What's changed since v1.6.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed configuration array deserializes as dictionary from YAML options. #779</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v160","title":"v1.6.0","text":"<p>What's changed since v1.5.0:</p> <ul> <li>Engine features:<ul> <li>Added support for YAML rules. #603<ul> <li>YAML rules evaluate an expression tree and return a result for each object.</li> <li>YAML provides an additional option for defining rules in addition to PowerShell script rules.</li> <li>Type and selector pre-conditions are supported.</li> <li>See about_PSRule_Rules for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added support for object source location in validation. #757</li> <li>Default rule source location <code>.ps-rule/</code> is automatically included. #742<ul> <li>Added <code>Include.Path</code> and <code>Include.Module</code> options to automatically include rule sources.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed target binding across multiple scopes. #762</li> </ul> </li> </ul> <p>What's changed since pre-release v1.6.0-B2108009:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v160-b2108009-pre-release","title":"v1.6.0-B2108009 (pre-release)","text":"<p>What's changed since pre-release v1.6.0-B2108003:</p> <ul> <li>Engine features:<ul> <li>Added support for YAML rules. #603<ul> <li>YAML rules evaluate an expression tree and return a result for each object.</li> <li>YAML provides an additional option for defining rules in addition to PowerShell script rules.</li> <li>Type and selector pre-conditions are supported.</li> <li>See about_PSRule_Rules for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v160-b2108003-pre-release","title":"v1.6.0-B2108003 (pre-release)","text":"<p>What's changed since pre-release v1.6.0-B2107008:</p> <ul> <li>Bug fixes:<ul> <li>Fixed target binding across multiple scopes. #762</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v160-b2107008-pre-release","title":"v1.6.0-B2107008 (pre-release)","text":"<p>What's changed since v1.5.0:</p> <ul> <li>General improvements:<ul> <li>Added support for object source location in validation. #757</li> <li>Default rule source location <code>.ps-rule/</code> is automatically included. #742<ul> <li>Added <code>Include.Path</code> and <code>Include.Module</code> options to automatically include rule sources.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v150","title":"v1.5.0","text":"<p>What's changed since v1.4.0:</p> <ul> <li>General improvements:<ul> <li>Added string selector conditions. #747<ul> <li>Use <code>startWith</code>, <code>contains</code>, and <code>endsWith</code> to check for a sub-string.</li> <li>Use <code>isString</code>, <code>isLower</code>, and <code>isUpper</code> to check for string type and casing.</li> <li>See about_PSRule_Selectors for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.2.1. #740</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed options schema should allow spacing after <code>@pre</code>. #743</li> <li>Fixed match selector expression passing on missing field. #745</li> </ul> </li> </ul> <p>What's changed since pre-release v1.5.0-B2107009:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v150-b2107009-pre-release","title":"v1.5.0-B2107009 (pre-release)","text":"<p>What's changed since pre-release v1.5.0-B2106006:</p> <ul> <li>General improvements:<ul> <li>Added string selector conditions. #747<ul> <li>Use <code>startWith</code>, <code>contains</code>, and <code>endsWith</code> to check for a sub-string.</li> <li>Use <code>isString</code>, <code>isLower</code>, and <code>isUpper</code> to check for string type and casing.</li> <li>See about_PSRule_Selectors for details.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.2.1. #740</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed options schema should allow spacing after <code>@pre</code>. #743</li> <li>Fixed match selector expression passing on missing field. #745</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v150-b2106006-pre-release","title":"v1.5.0-B2106006 (pre-release)","text":"<p>What's changed since v1.4.0:</p> <ul> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.2.0. #736</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140","title":"v1.4.0","text":"<p>What's changed since v1.3.0:</p> <ul> <li>General improvements:<ul> <li>PSRule banner can be configured in output when using <code>Assert-PSRule</code>. #708</li> <li>Input source location of objects are included in results.<ul> <li>Input source location of objects from JSON and YAML input files are read automatically. #624</li> <li>Input source location of objects from the pipeline are read from properties. #729</li> </ul> </li> <li>Assert output improvements:<ul> <li>Added support for Visual Studio Code with <code>VisualStudioCode</code> style. #731<ul> <li>Updated output format provides support for problem matchers in task output.</li> </ul> </li> <li>Automatically detect output style from environment variables. #732<ul> <li>Assert-PSRule now defaults to <code>Detect</code> instead of <code>Client</code>.</li> </ul> </li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Improved support for version constraints by:<ul> <li>Constraints can include prerelease versions of other matching versions. #714</li> <li>Constraints support using a <code>@prerelease</code> or <code>@pre</code> to include prerelease versions. #717</li> <li>Constraint sets allow multiple constraints to be joined together. #715</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed prerelease constraint handling for prerelease versions. #712</li> <li>Fixed null reference in convention for nested exceptions. #725</li> </ul> </li> </ul> <p>What's changed since pre-release v1.4.0-B2105041:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105041-pre-release","title":"v1.4.0-B2105041 (pre-release)","text":"<p>What's changed since pre-release v1.4.0-B2105032:</p> <ul> <li>General improvements:<ul> <li>Source location of objects from the pipeline are read from properties. #729</li> <li>Assert output improvements:<ul> <li>Added support for Visual Studio Code with <code>VisualStudioCode</code> style. #731<ul> <li>Updated output format provides support for problem matchers in task output.</li> </ul> </li> <li>Automatically detect output style from environment variables. #732<ul> <li>Assert-PSRule now defaults to <code>Detect</code> instead of <code>Client</code>.</li> </ul> </li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105032-pre-release","title":"v1.4.0-B2105032 (pre-release)","text":"<p>What's changed since pre-release v1.4.0-B2105019:</p> <ul> <li>Bug fixes:<ul> <li>Fixed null reference in convention for nested exceptions. #725</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105019-pre-release","title":"v1.4.0-B2105019 (pre-release)","text":"<p>What's changed since pre-release v1.4.0-B2105004:</p> <ul> <li>General improvements:<ul> <li>Source location of objects are included in results.<ul> <li>Source location of objects from JSON and YAML input files are read automatically. #624</li> </ul> </li> <li>Improved support for version constraints by:<ul> <li>Constraints can include prerelease versions of other matching versions. #714</li> <li>Constraints support using a <code>@prerelease</code> or <code>@pre</code> to include prerelease versions. #717</li> <li>Constraint sets allow multiple constraints to be joined together. #715</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed prerelease constraint handling for prerelease versions. #712</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v140-b2105004-pre-release","title":"v1.4.0-B2105004 (pre-release)","text":"<p>What's changed since v1.3.0:</p> <ul> <li>General improvements:<ul> <li>PSRule banner can be configured in output when using <code>Assert-PSRule</code>. #708</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130","title":"v1.3.0","text":"<p>What's changed since v1.2.0:</p> <ul> <li>Engine features:<ul> <li>Options can be configured with environment variables. #691<ul> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Exclude <code>.git</code> sub-directory by default for recursive scans. #697<ul> <li>Added <code>Input.IgnoreGitPath</code> option to configure inclusion of <code>.git</code> path.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added file path assertion helpers. #679<ul> <li>Added <code>WithinPath</code> to check the file path field is within a specified path.</li> <li>Added <code>NotWithinPath</code> to check the file path field is not within a specified path</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added DateTime type assertion helper. #680<ul> <li>Added <code>IsDateTime</code> to check of object field is <code>[DateTime]</code>.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improved numeric comparison assertion helpers to compare <code>[DateTime]</code> fields. #685<ul> <li><code>Less</code>, <code>LessOrEqual</code>, <code>Greater</code>, and <code>GreaterOrEqual</code> compare the number of days from the current time.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improved handling of field names for objects implementing <code>IList</code>, <code>IEnumerable</code>, and index properties. #692</li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.1.1. #690</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed expected DocumentEnd got SequenceEnd. #698</li> </ul> </li> </ul> <p>What's changed since pre-release v1.3.0-B2105004:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2105004-pre-release","title":"v1.3.0-B2105004 (pre-release)","text":"<p>What's changed since pre-release v1.3.0-B2104042:</p> <ul> <li>Engine features:<ul> <li>Options can be configured with environment variables. #691<ul> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Exclude <code>.git</code> sub-directory by default for recursive scans. #697<ul> <li>Added <code>Input.IgnoreGitPath</code> option to configure inclusion of <code>.git</code> path.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2104042-pre-release","title":"v1.3.0-B2104042 (pre-release)","text":"<p>What's changed since pre-release v1.3.0-B2104030:</p> <ul> <li>Bug fixes:<ul> <li>Fixed expected DocumentEnd got SequenceEnd. #698</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2104030-pre-release","title":"v1.3.0-B2104030 (pre-release)","text":"<p>What's changed since pre-release v1.3.0-B2104021:</p> <ul> <li>General improvements:<ul> <li>Improved handling of field names for objects implementing <code>IList</code>, <code>IEnumerable</code>, and index properties. #692</li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet dependency to 11.1.1. #690</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v130-b2104021-pre-release","title":"v1.3.0-B2104021 (pre-release)","text":"<p>What's changed since v1.2.0:</p> <ul> <li>General improvements:<ul> <li>Added file path assertion helpers. #679<ul> <li>Added <code>WithinPath</code> to check the file path field is within a specified path.</li> <li>Added <code>NotWithinPath</code> to check the file path field is not within a specified path</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added DateTime type assertion helper. #680<ul> <li>Added <code>IsDateTime</code> to check of object field is <code>[DateTime]</code>.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improved numeric comparison assertion helpers to compare <code>[DateTime]</code> fields. #685<ul> <li><code>Less</code>, <code>LessOrEqual</code>, <code>Greater</code>, and <code>GreaterOrEqual</code> compare the number of days from the current time.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120","title":"v1.2.0","text":"<p>What's changed since v1.1.0:</p> <ul> <li>Engine features:<ul> <li>Added support for extensibility with conventions. #650<ul> <li>Conventions provide an extensibility point within PSRule to execute actions within the pipeline.</li> <li>A convention can expose <code>Begin</code>, <code>Process</code>, and <code>End</code> blocks.</li> <li>In additional to within rules <code>$PSRule.Data</code> can be accessed from <code>Begin</code> and <code>Process</code> blocks.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> <li>Added support for object expansion with conventions. #661<ul> <li>Use the <code>$PSRule.Import</code> method to import child source objects into the pipeline.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> <li>Added support for complex pre-conditions with selectors. #649<ul> <li>See about_PSRule_Selectors for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added support for preferring automatic binding over custom binding configurations. #670<ul> <li>Added the <code>Binding.PreferTargetInfo</code> option to prefer target info specified by the object.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added strong apiVersion to resource types. #647<ul> <li>Resource schemas now support an <code>apiVersion</code> field.</li> <li>The <code>apiVersion</code> field is optional but recommended.</li> <li>Resources without a <code>apiVersion</code> field will not be supported from PSRule v2.</li> <li>Added warning to flag baseline without <code>apiVersion</code> set.</li> </ul> </li> <li>Added support for detecting files headers from additional file extensions using <code>FileHeader</code>. #664<ul> <li>Added <code>.bicep</code>, <code>.csx</code>, <code>.jsx</code>, <code>.groovy</code>, <code>.java</code>, <code>.json</code>, <code>.jsonc</code>, <code>.scala</code>, <code>.rb</code>, <code>.bat</code>, <code>.cmd</code>.</li> <li>Added support for <code>Jenkinsfile</code> and <code>Dockerfile</code> without an extension.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for automatic type binding with files that do not have a file extension. #665</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed dependent rule execution is skipped for consequent input objects. #657</li> </ul> </li> </ul> <p>What's changed since pre-release v1.2.0-B2103043:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103043-pre-release","title":"v1.2.0-B2103043 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103031:</p> <ul> <li>Engine features:<ul> <li>Added support for complex pre-conditions with selectors. #649</li> </ul> </li> <li>General improvements:<ul> <li>Added support for preferring automatic binding over custom binding configurations. #670<ul> <li>Added the <code>Binding.PreferTargetInfo</code> option to prefer target info specified by the object.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added strong apiVersion to resource types. #647<ul> <li>Resource schemas now support an <code>apiVersion</code> field.</li> <li>The <code>apiVersion</code> field is optional but recommended.</li> <li>Resources without a <code>apiVersion</code> field will not be supported from PSRule v2.</li> <li>Added warning to flag baseline without <code>apiVersion</code> set.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103031-pre-release","title":"v1.2.0-B2103031 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103023:</p> <ul> <li>General improvements:<ul> <li>Added support for detecting files headers from additional file extensions. #664<ul> <li>Added <code>.bicep</code>, <code>.csx</code>, <code>.jsx</code>, <code>.groovy</code>, <code>.java</code>, <code>.json</code>, <code>.jsonc</code>, <code>.scala</code>, <code>.rb</code>, <code>.bat</code>, <code>.cmd</code>.</li> <li>Added support for <code>Jenkinsfile</code> and <code>Dockerfile</code> without an extension.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for automatic type binding with files that do not have a file extension. #665</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103023-pre-release","title":"v1.2.0-B2103023 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103016:</p> <ul> <li>Engine features:<ul> <li>Added support for object expansion with conventions. #661<ul> <li>Use the <code>$PSRule.Import</code> method to import child source objects into the pipeline.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103016-pre-release","title":"v1.2.0-B2103016 (pre-release)","text":"<p>What's changed since pre-release v1.2.0-B2103008:</p> <ul> <li>Bug fixes:<ul> <li>Fixed dependent rule execution is skipped for consequent input objects. #657</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v120-b2103008-pre-release","title":"v1.2.0-B2103008 (pre-release)","text":"<p>What's changed since v1.1.0:</p> <ul> <li>Engine features:<ul> <li>Added support for extensibility with conventions. #650<ul> <li>Conventions provide an extensibility point within PSRule to execute actions within the pipeline.</li> <li>A convention can expose <code>Begin</code>, <code>Process</code>, and <code>End</code> blocks.</li> <li>In additional to within rules <code>$PSRule.Data</code> can be accessed from <code>Begin</code> and <code>Process</code> blocks.</li> <li>See about_PSRule_Conventions for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v110","title":"v1.1.0","text":"<p>What's changed since v1.0.3:</p> <ul> <li>Engine features:<ul> <li>Added assertion helpers. #640<ul> <li>Added <code>NotHasField</code> to check object does not have any of the specified fields.</li> <li>Added <code>Null</code> to check field value is null.</li> <li>Added <code>NotNull</code> to check field value is not null.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added type assertion helpers. #635<ul> <li>Added <code>IsNumeric</code> to check field value is a numeric types.</li> <li>Added <code>IsInteger</code> to check field value is an integer types.</li> <li>Added <code>IsBoolean</code> to check field value is a boolean.</li> <li>Added <code>IsArray</code> to check field value is an array.</li> <li>Added <code>IsString</code> to check field value is a string.</li> <li>Added <code>TypeOf</code> to check field value is a specified type.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added content helpers. #637<ul> <li>Added <code>$PSRule.GetContentFirstOrDefault</code> to get content and return the first object.</li> <li>Added <code>$PSRule.GetContentField</code> to get the field from content objects.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Updated <code>HasJsonSchema</code> assertion helper. #636<ul> <li>The URI scheme can optionally be ignored for <code>http://</code> or <code>https://</code> URIs.</li> <li>The fragment <code>#</code> is ignored.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added support for <code>-Outcome</code> and <code>-As</code> to produce filtered output from <code>Assert-PSRule</code>. #643<ul> <li>Configure <code>Output.As</code> with <code>Summary</code> to produce summarized results per object.</li> <li>Configure <code>Output.Outcome</code> to limit output to <code>Fail</code> or <code>Error</code>.</li> <li>See Assert-PSRule for details.</li> </ul> </li> </ul> </li> </ul> <p>What's changed since pre-release v1.1.0-B2102029:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v110-b2102029-pre-release","title":"v1.1.0-B2102029 (pre-release)","text":"<p>What's changed since pre-release v1.1.0-B2102024:</p> <ul> <li>General improvements:<ul> <li>Added support for <code>-Outcome</code> and <code>-As</code> to produce filtered output from <code>Assert-PSRule</code>. #643<ul> <li>Configure <code>Output.As</code> with <code>Summary</code> to produce summarized results per object.</li> <li>Configure <code>Output.Outcome</code> to limit output to <code>Fail</code> or <code>Error</code>.</li> <li>See Assert-PSRule for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v110-b2102024-pre-release","title":"v1.1.0-B2102024 (pre-release)","text":"<p>What's changed since pre-release v1.1.0-B2102019:</p> <ul> <li>Engine features:<ul> <li>Added assertion helpers. #640<ul> <li>Added <code>NotHasField</code> to check object does not have any of the specified fields.</li> <li>Added <code>Null</code> to check field value is null.</li> <li>Added <code>NotNull</code> to check field value is not null.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v110-b2102019-pre-release","title":"v1.1.0-B2102019 (pre-release)","text":"<p>What's changed since v1.0.3:</p> <ul> <li>Engine features:<ul> <li>Added type assertion helpers. #635<ul> <li>Added <code>IsNumeric</code> to check field value is a numeric types.</li> <li>Added <code>IsInteger</code> to check field value is an integer types.</li> <li>Added <code>IsBoolean</code> to check field value is a boolean.</li> <li>Added <code>IsArray</code> to check field value is an array.</li> <li>Added <code>IsString</code> to check field value is a string.</li> <li>Added <code>TypeOf</code> to check field value is a specified type.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Added content helpers. #637<ul> <li>Added <code>$PSRule.GetContentFirstOrDefault</code> to get content and return the first object.</li> <li>Added <code>$PSRule.GetContentField</code> to get the field from content objects.</li> <li>See about_PSRule_Variables for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Updated <code>HasJsonSchema</code> assertion helper. #636<ul> <li>The URI scheme can optionally be ignored for <code>http://</code> or <code>https://</code> URIs.</li> <li>The fragment <code>#</code> is ignored.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v103","title":"v1.0.3","text":"<p>What's changed since v1.0.2:</p> <ul> <li>Bug fixes:<ul> <li>Fixed reason reported fields for <code>HasField</code> and <code>HasFields</code> assertion helpers. #632</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v102","title":"v1.0.2","text":"<p>What's changed since v1.0.1:</p> <ul> <li>Engineering:<ul> <li>Bump Manatee.Json dependency to 13.0.5. #619</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed <code>GetContent</code> processing of <code>InputFileInfo</code>. #625</li> <li>Fixed null reference of rule reason with wide output. #626</li> <li>Fixed markdown help handling of inline code blocks with <code>[</code>. #627</li> <li>Fixed markdown help inclusion of fenced code blocks in notes and description. #628</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v101","title":"v1.0.1","text":"<p>What's changed since v1.0.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed module source key has already been added. #608</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v1/#v100","title":"v1.0.0","text":"<p>What's changed since v0.22.0:</p> <ul> <li>General improvements:<ul> <li>Added rule help link in failed <code>Assert-PSRule</code> output. #595</li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removed deprecated <code>$Rule</code> properties. #495</li> <li>Bump Manatee.Json dependency to 13.0.4. #591</li> </ul> </li> </ul> <p>What's changed since pre-release v1.0.0-B2011028:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v1/#v100-b2011028-pre-release","title":"v1.0.0-B2011028 (pre-release)","text":"<p>What's changed since v0.22.0:</p> <ul> <li>General improvements:<ul> <li>Added rule help link in failed <code>Assert-PSRule</code> output. #595</li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removed deprecated <code>$Rule</code> properties. #495</li> <li>Bump Manatee.Json dependency to 13.0.4. #591</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Important notes:</p> <ul> <li>Several options have been renamed and the old names will be removed in v3.   See deprecations for details.</li> <li> <p>Several properties of rule and language block elements will be removed from v3.   See deprecations for details.</p> </li> </ul> <p>Experimental features:</p> <ul> <li>Baseline groups allow you to use a friendly name to reference baselines.   See baselines for more information.</li> <li>Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition.   See functions for more information.</li> <li>Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties.   See sub-selectors for more information.</li> <li> <p>Processing of changes files only within a pipeline.   See creating your pipeline for more information.</p> </li> </ul> <p>Attention</p> <p>We are currently working towards the next release of PSRule. For more information see v3 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.</p>"},{"location":"CHANGELOG-v2/#v290","title":"v2.9.0","text":"<p>What's changed since release v2.8.1:</p> <ul> <li>New features:<ul> <li>Added sub-selector quantifiers for <code>allOf</code> or <code>anyOf</code> operators by @BernieWhite.   #1423<ul> <li>Quantifiers allow you to specify the number of matches with <code>count</code>, <code>less</code>, <code>lessOrEqual</code>, <code>greater</code>, or <code>greaterOrEqual</code>.</li> <li>See Sub-selectors for more information.</li> </ul> </li> <li>Added support for new functions by @BernieWhite.   #1422<ul> <li>Added support for <code>padLeft</code>, and <code>padRight</code>.</li> </ul> </li> <li>Experimental: Added support for baseline groups by @BernieWhite.   #1541<ul> <li>Baseline groups allow you to reference a baseline by a friendly name.</li> <li>Update the baseline group to point to a new baseline.</li> <li>Currently only a single baseline can be referenced by a baseline group.</li> <li>See baselines for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added style and improved handling for restore command by @BernieWhite.   #1152</li> <li>Important change: Rename of execution options by @BernieWhite.   #1456<ul> <li>Renamed options allow configuration of output level as <code>Ignore</code>, <code>Warn</code>, <code>Error</code>, or <code>Debug</code>.</li> <li><code>Execution.AliasReferenceWarning</code> is replaced with <code>Execution.AliasReference</code>.</li> <li><code>Execution.InconclusiveWarning</code> is replaced with <code>Execution.RuleInconclusive</code>.</li> <li><code>Execution.InvariantCultureWarning</code> is replaced with <code>Execution.InvariantCulture</code>.</li> <li><code>Execution.NotProcessedWarning</code> is replaced with <code>Execution.UnprocessedObject</code>.</li> <li>Deprecated <code>AliasReferenceWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InconclusiveWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InvariantCultureWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>NotProcessedWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Improved schema display names by @BernieWhite.   #1488</li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.1.   #1510</li> <li>Bump Microsoft.NET.Test.Sdk to v17.6.2.   #1544</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.6.0.   #1534</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed tool output on access denied to path by @BernieWhite.   #1490</li> <li>Fixed tool exit code on error or failure by @BernieWhite.   #1491</li> <li>Fixed include local not automatically being enabled for default module baseline by @BernieWhite.   #1506</li> </ul> </li> </ul> <p>What's changed since pre-release v2.9.0-B0068:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v290-b0068-pre-release","title":"v2.9.0-B0068 (pre-release)","text":"<p>What's changed since pre-release v2.9.0-B0033:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for baseline groups by @BernieWhite.   #1541<ul> <li>Baseline groups allow you to reference a baseline by a friendly name.</li> <li>Update the baseline group to point to a new baseline.</li> <li>Currently only a single baseline can be referenced by a baseline group.</li> <li>See baselines for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added style and improved handling for restore command by @BernieWhite.   #1152</li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.6.2.   #1544</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.6.0.   #1534</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed include local not automatically being enabled for default module baseline by @BernieWhite.   #1506</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v290-b0033-pre-release","title":"v2.9.0-B0033 (pre-release)","text":"<p>What's changed since pre-release v2.9.0-B0013:</p> <ul> <li>New features:<ul> <li>Added sub-selector quantifiers for <code>allOf</code> or <code>anyOf</code> operators by @BernieWhite.   #1423<ul> <li>Quantifiers allow you to specify the number of matches with <code>count</code>, <code>less</code>, <code>lessOrEqual</code>, <code>greater</code>, or <code>greaterOrEqual</code>.</li> <li>See Sub-selectors for more information.</li> </ul> </li> <li>Added support for new functions by @BernieWhite.   #1422<ul> <li>Added support for <code>padLeft</code>, and <code>padRight</code>.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v290-b0013-pre-release","title":"v2.9.0-B0013 (pre-release)","text":"<p>What's changed since release v2.8.1:</p> <ul> <li>General improvements:<ul> <li>Important change: Rename of execution options by @BernieWhite.   #1456<ul> <li>Renamed options allow configuration of output level as <code>Ignore</code>, <code>Warn</code>, <code>Error</code>, or <code>Debug</code>.</li> <li><code>Execution.AliasReferenceWarning</code> is replaced with <code>Execution.AliasReference</code>.</li> <li><code>Execution.InconclusiveWarning</code> is replaced with <code>Execution.RuleInconclusive</code>.</li> <li><code>Execution.InvariantCultureWarning</code> is replaced with <code>Execution.InvariantCulture</code>.</li> <li><code>Execution.NotProcessedWarning</code> is replaced with <code>Execution.UnprocessedObject</code>.</li> <li>Deprecated <code>AliasReferenceWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InconclusiveWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>InvariantCultureWarning</code> option, which will be removed in v3.</li> <li>Deprecated <code>NotProcessedWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Improved schema display names by @BernieWhite.   #1488</li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.1.   #1510</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.5.0.   #1455</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed tool output on access denied to path by @BernieWhite.   #1490</li> <li>Fixed tool exit code on error or failure by @BernieWhite.   #1491</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v281","title":"v2.8.1","text":"<p>What's changed since release v2.8.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed wrong message for excluded rules by @BernieWhite.   #1493</li> <li>Fixed job summary reports completed time by @BernieWhite.   #1492</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280","title":"v2.8.0","text":"<p>What's changed since release v2.7.0:</p> <ul> <li>General improvements:<ul> <li>Important change: Replaced <code>SuppressedRuleWarning</code> execution option with <code>RuleSuppressed</code> by @BernieWhite.   #1456<ul> <li>Improved options for output of suppressed rules with <code>RuleSuppressed</code> option.</li> <li>Deprecated <code>SuppressedRuleWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Added support for logging excluded rules by @BernieWhite.   #1432<ul> <li>Configure <code>Execution.RuleExcluded</code> to control output level of excluded rules as <code>Ignore</code>, <code>Warn</code>, <code>Error</code>, or <code>Debug</code>.</li> </ul> </li> <li>Added additional options to schema for PSRule for Azure by @BernieWhite.   #1446</li> <li>Improved error message for failing to read options file by @BernieWhite.   #1433</li> <li>Added support for import within initialize block by @BernieWhite.   #1448</li> <li>Added support for direct typing on import by @BernieWhite.   #1449<ul> <li>Use the <code>$PSRule.ImportWithType</code> method to import an object with a specific type.</li> </ul> </li> <li>Added support for case sensitivity matching with <code>match</code> and <code>notMatch</code> expressions by @BernieWhite.   #1480</li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.0.   #1414   Bump Microsoft.CodeAnalysis.Common to v4.4.0.   #1341</li> <li>Bump BenchmarkDotNet to v0.13.5.   #1413</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5.   #1413</li> <li>Bump Microsoft.NET.Test.Sdk to v17.5.0.   #1442</li> <li>Bump Newtonsoft.Json to v13.0.3.   #1467</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1.   #1468</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite.   #1405</li> <li>Fixed no output with using job summary with as summary by @BernieWhite.   #1483<ul> <li>Fixed output and added error for unsupported scenarios.</li> </ul> </li> <li>Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite.   #1083</li> <li>Fixed LocalizedData is not exposed to conventions by @BernieWhite.   #1477</li> <li>Fixed problem binding when not set locally by @BernieWhite.   #1473</li> </ul> </li> </ul> <p>What's changed since pre-release v2.8.0-B0171:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0171-pre-release","title":"v2.8.0-B0171 (pre-release)","text":"<p>What's changed since pre-release v2.8.0-B0121:</p> <ul> <li>General improvements:<ul> <li>Added support for case sensitivity matching with <code>match</code> and <code>notMatch</code> expressions by @BernieWhite.   #1480</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed no output with using job summary with as summary by @BernieWhite.   #1483<ul> <li>Fixed output and added error for unsupported scenarios.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0121-pre-release","title":"v2.8.0-B0121 (pre-release)","text":"<p>What's changed since pre-release v2.8.0-B0076:</p> <ul> <li>Bug fixes:<ul> <li>Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite.   #1083</li> <li>Fixed LocalizedData is not exposed to conventions by @BernieWhite.   #1477</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0076-pre-release","title":"v2.8.0-B0076 (pre-release)","text":"<p>What's changed since pre-release v2.8.0-B0034:</p> <ul> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to v13.0.3.   #1467</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1.   #1468</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed problem binding when not set locally by @BernieWhite.   #1473</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v280-b0034-pre-release","title":"v2.8.0-B0034 (pre-release)","text":"<p>What's changed since v2.7.0:</p> <ul> <li>General improvements:<ul> <li>Important change: Replaced <code>SuppressedRuleWarning</code> execution option with <code>RuleSuppressed</code> by @BernieWhite.   #1456<ul> <li>Improved options for output of suppressed rules with <code>RuleSuppressed</code> option.</li> <li>Deprecated <code>SuppressedRuleWarning</code> option, which will be removed in v3.</li> </ul> </li> <li>Added support for logging excluded rules by @BernieWhite.   #1432</li> <li>Added additional options to schema for PSRule for Azure by @BernieWhite.   #1446</li> <li>Improved error message for failing to read options file by @BernieWhite.   #1433</li> <li>Added support for import within initialize block by @BernieWhite.   #1448</li> <li>Added support for direct typing on import by @BernieWhite.   #1449<ul> <li>Use the <code>$PSRule.ImportWithType</code> method to import an object with a specific type.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Pester to v5.4.0.   #1414</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.0.   #1374   Bump Microsoft.CodeAnalysis.Common to v4.4.0.   #1341</li> <li>Bump BenchmarkDotNet to v0.13.5.   #1413</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5.   #1413</li> <li>Bump Microsoft.NET.Test.Sdk to v17.5.0.   #1442</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite.   #1405</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270","title":"v2.7.0","text":"<p>What's changed since v2.6.0:</p> <ul> <li>New features:<ul> <li>Added API version date comparison assertion method and expression by @BernieWhite.   #1356</li> <li>Added support for new functions by @BernieWhite.   #1227<ul> <li>Added support for <code>trim</code>, <code>replace</code>, <code>split</code>, <code>first</code>, and <code>last</code>.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added support target scope by @BernieWhite.   #1350</li> <li>Added support for <code>hasValue</code> expression with <code>scope</code> by @BernieWhite.   #1382</li> <li>Return target object scope as an array by @BernieWhite.   #1383</li> <li>Improve support of string comparisons to support an array of strings by @BernieWhite.   #1384</li> <li>Added help properties to rules from YAML/ JSON resources by @BernieWhite.   #1386</li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to v13.0.2.   #1358</li> <li>Bump System.Drawing.Common to v7.0.0.   #1332</li> <li>Bump Microsoft.NET.Test.Sdk to v17.4.1.   #1389</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed exception with comments in JSON baselines by @BernieWhite.   #1336</li> <li>Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite.   #1348</li> <li>Fixed exception calling <code>RuleSource</code> value cannot be null by @BernieWhite.   #1343</li> <li>Fixed null reference for link property by @BernieWhite.   #1393</li> <li>Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite.   #1394</li> <li>Fixed CLI failed to load required assemblies by @BernieWhite.   #1361</li> <li>Fixed CLI ignores modules specified in <code>Include.Modules</code> by @BernieWhite.   #1362</li> <li>Fixed job summary directory creation by @BernieWhite.   #1353</li> <li>Fixed same key for ref and name by @BernieWhite #1354</li> <li>Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite.   #1376</li> <li>Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite.   #1378</li> <li>Fixed loop stuck parsing JSON <code>allOf</code> <code>not</code> rule condition by @BernieWhite.   #1370</li> <li>Fixed handling of uint64 with <code>LessOrEqual</code> assertion method by @BernieWhite.   #1366</li> </ul> </li> </ul> <p>What's changed since pre-release v2.7.0-B0126:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0126-pre-release","title":"v2.7.0-B0126 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0097:</p> <ul> <li>Bug fixes:<ul> <li>Fixed null reference for link property by @BernieWhite.   #1393</li> <li>Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite.   #1394</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0097-pre-release","title":"v2.7.0-B0097 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0070:</p> <ul> <li>General improvements:<ul> <li>Added support for <code>hasValue</code> expression with <code>scope</code> by @BernieWhite.   #1382</li> <li>Return target object scope as an array by @BernieWhite.   #1383</li> <li>Improve support of string comparisons to support an array of strings by @BernieWhite.   #1384</li> <li>Added help properties to rules from YAML/ JSON resources by @BernieWhite.   #1386</li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to v13.0.2.   #1358</li> <li>Bump System.Drawing.Common to v7.0.0.   #1332</li> <li>Bump Microsoft.NET.Test.Sdk to v17.4.1.   #1389</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0070-pre-release","title":"v2.7.0-B0070 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0049:</p> <ul> <li>Bug fixes:<ul> <li>Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite.   #1376</li> <li>Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite.   #1378</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0049-pre-release","title":"v2.7.0-B0049 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0031:</p> <ul> <li>Bug fixes:<ul> <li>Fixed loop stuck parsing JSON <code>allOf</code> <code>not</code> rule condition by @BernieWhite.   #1370</li> <li>Fixed handling of uint64 with <code>LessOrEqual</code> assertion method by @BernieWhite.   #1366</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0031-pre-release","title":"v2.7.0-B0031 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0016:</p> <ul> <li>New features:<ul> <li>Added API version date comparison assertion method and expression by @BernieWhite.   #1356</li> <li>Added support for new functions by @BernieWhite.   #1227<ul> <li>Added support for <code>trim</code>, <code>replace</code>, <code>split</code>, <code>first</code>, and <code>last</code>.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed CLI failed to load required assemblies by @BernieWhite.   #1361</li> <li>Fixed CLI ignores modules specified in <code>Include.Modules</code> by @BernieWhite.   #1362</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0016-pre-release","title":"v2.7.0-B0016 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0006:</p> <ul> <li>Bug fixes:<ul> <li>Fixed job summary directory creation by @BernieWhite.   #1353</li> <li>Fixed same key for ref and name by @BernieWhite #1354</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0006-pre-release","title":"v2.7.0-B0006 (pre-release)","text":"<p>What's changed since pre-release v2.7.0-B0001:</p> <ul> <li>General improvements:<ul> <li>Added support target scope by @BernieWhite.   #1350</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed exception with comments in JSON baselines by @BernieWhite.   #1336</li> <li>Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite.   #1348</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v270-b0001-pre-release","title":"v2.7.0-B0001 (pre-release)","text":"<p>What's changed since v2.6.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed exception calling <code>RuleSource</code> value cannot be null by @BernieWhite.   #1343</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v260","title":"v2.6.0","text":"<p>What's changed since v2.5.3:</p> <ul> <li>New features:<ul> <li>Added support for generating job summaries by @BernieWhite.   #1264<ul> <li>Job summaries provide a markdown output for pipelines in addition to other supported output formats.</li> <li>To use, configure the <code>Output.JobSummaryPath</code> option.</li> </ul> </li> <li>Added support for time bound suppression groups by @BernieWhite.   #1335<ul> <li>Suppression groups can be configured to expire after a specified time by setting the <code>spec.expiresOn</code> property.</li> <li>When a suppression group expires, the suppression group will generate a warning by default.</li> <li>Configure the <code>Execution.SuppressionGroupExpired</code> option to ignore or error on expired suppression groups.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.4.0.   #1331</li> <li>Bump PSScriptAnalyzer to v1.21.0.   #1318</li> <li>Class clean up and documentation by @BernieWhite.   #1186</li> </ul> </li> </ul> <p>What's changed since pre-release v2.6.0-B0034:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v260-b0034-pre-release","title":"v2.6.0-B0034 (pre-release)","text":"<p>What's changed since pre-release v2.6.0-B0013:</p> <ul> <li>New features:<ul> <li>Added support for generating job summaries by @BernieWhite.   #1264<ul> <li>Job summaries provide a markdown output for pipelines in addition to other supported output formats.</li> <li>To use, configure the <code>Output.JobSummaryPath</code> option.</li> </ul> </li> <li>Added support for time bound suppression groups by @BernieWhite.   #1335<ul> <li>Suppression groups can be configured to expire after a specified time by setting the <code>spec.expiresOn</code> property.</li> <li>When a suppression group expires, the suppression group will generate a warning by default.</li> <li>Configure the <code>Execution.SuppressionGroupExpired</code> option to ignore or error on expired suppression groups.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.4.0.   #1331</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v260-b0013-pre-release","title":"v2.6.0-B0013 (pre-release)","text":"<p>What's changed since v2.5.3:</p> <ul> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.3.2.   #1283</li> <li>Bump PSScriptAnalyzer to v1.21.0.   #1318</li> <li>Class clean up and documentation by @BernieWhite.   #1186</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v253","title":"v2.5.3","text":"<p>What's changed since v2.5.2:</p> <ul> <li>Bug fixes:<ul> <li>Fixed incorrect XML header for encoding by @BernieWhite.   #1322</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v252","title":"v2.5.2","text":"<p>What's changed since v2.5.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed NUnit output does not escape characters in all result properties by @BernieWhite.   #1316</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v251","title":"v2.5.1","text":"<p>What's changed since v2.5.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed <code>In</code> with array source object and dot object path by @BernieWhite.   #1314</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250","title":"v2.5.0","text":"<p>What's changed since v2.4.2:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for only processing changed files by @BernieWhite.   #688<ul> <li>To ignore unchanged files, set the <code>Input.IgnoreUnchangedPath</code> option to <code>true</code>.</li> <li>See creating your pipeline for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added labels metadata from grouping and filtering rules by @BernieWhite.   #1272<ul> <li>Labels are metadata that extends on tags to provide a more structured way to group rules.</li> <li>Rules can be classified by setting the <code>metadata.labels</code> property or <code>-Labels</code> parameter.</li> </ul> </li> <li>Provide unblock for command line tools by @BernieWhite.   #1261</li> </ul> </li> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.3.1.   #1248</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite.   #1249<ul> <li>To use minimal initial session state set <code>Execution.InitialSessionState</code> to <code>Minimal</code>.</li> </ul> </li> <li>Fixed unhandled exception with GetRootedPath by @BernieWhite.   #1251</li> <li>Fixed Dockerfile case sensitivity by @BernieWhite.   #1269</li> </ul> </li> </ul> <p>What's changed since pre-release v2.5.0-B0080:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0080-pre-release","title":"v2.5.0-B0080 (pre-release)","text":"<p>What's changed since pre-release v2.5.0-B0045:</p> <ul> <li>Bug fixes:<ul> <li>Fixed exception with <code>PathExpressionBuilder.GetAllRecurse</code> by @BernieWhite.   #1301</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0045-pre-release","title":"v2.5.0-B0045 (pre-release)","text":"<p>What's changed since pre-release v2.5.0-B0015:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for only processing changed files by @BernieWhite.   #688<ul> <li>To ignore unchanged files, set the <code>Input.IgnoreUnchangedPath</code> option to <code>true</code>.</li> <li>See creating your pipeline for more information.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Added labels metadata from grouping and filtering rules by @BernieWhite.   #1272<ul> <li>Labels are metadata that extends on tags to provide a more structured way to group rules.</li> <li>Rules can be classified by setting the <code>metadata.labels</code> property or <code>-Labels</code> parameter.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed Dockerfile case sensitivity by @BernieWhite.   #1269</li> <li>Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz.   #1286 #1285</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0015-pre-release","title":"v2.5.0-B0015 (pre-release)","text":"<p>What's changed since pre-release v2.5.0-B0004:</p> <ul> <li>General improvements:<ul> <li>Provide unblock for command line tools by @BernieWhite.   #1261</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v250-b0004-pre-release","title":"v2.5.0-B0004 (pre-release)","text":"<p>What's changed since v2.4.0:</p> <ul> <li>Engineering:<ul> <li>Bump Microsoft.NET.Test.Sdk to v17.3.1.   #1248</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite.   #1249<ul> <li>To use minimal initial session state set <code>Execution.InitialSessionState</code> to <code>Minimal</code>.</li> </ul> </li> <li>Fixed unhandled exception with GetRootedPath by @BernieWhite.   #1251</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v242","title":"v2.4.2","text":"<p>What's changed since v2.4.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixed exception with <code>PathExpressionBuilder.GetAllRecurse</code> by @BernieWhite.   #1301</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v241","title":"v2.4.1","text":"<p>What's changed since v2.4.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz.   #1286 #1285</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240","title":"v2.4.0","text":"<p>What's changed since v2.3.2:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite.   #1227 #1016<ul> <li>Added conversion functions <code>boolean</code>, <code>string</code>, and <code>integer</code>.</li> <li>Added lookup functions <code>configuration</code>, and <code>path</code>.</li> <li>Added string functions <code>concat</code>, <code>substring</code>.</li> <li>See functions for more information.</li> </ul> </li> <li>Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite.   #1024 #1045<ul> <li>Sub-selector pre-conditions add an additional expression to determine if a rule is executed.</li> <li>Sub-selector object filters provide an way to filter items from list properties.</li> <li>See sub-selectors for more information.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Improvements to PSRule engine API documentation by @BernieWhite.   #1186</li> <li>Updates to PSRule engine API by @BernieWhite.   #1152<ul> <li>Added tool support for baselines parameter.</li> <li>Added module path discovery.</li> <li>Added output for verbose and debug messages.</li> </ul> </li> <li>Bump support projects to .NET 6 by @BernieWhite.   #1209</li> <li>Bump Microsoft.NET.Test.Sdk to v17.3.0.   #1213</li> <li>Bump BenchmarkDotNet to v0.13.2.   #1241</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2.   #1242</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite.   #1229<ul> <li>Added <code>Execution.DuplicateResourceId</code> option to configure PSRule behaviour.</li> <li>By default, duplicate resource identifiers return an error.</li> </ul> </li> <li>Fixed exception on JSON baseline without a synopsis by @BernieWhite.   #1230</li> <li>Fixed repository information not in output by @BernieWhite.   #1219</li> </ul> </li> </ul> <p>What's changed since pre-release v2.4.0-B0091:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0091-pre-release","title":"v2.4.0-B0091 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0063:</p> <ul> <li>Engineering:<ul> <li>Bump BenchmarkDotNet to v0.13.2.   #1241</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2.   #1242</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0063-pre-release","title":"v2.4.0-B0063 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0039:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite.   #1024 #1045<ul> <li>Sub-selector pre-conditions add an additional expression to determine if a rule is executed.</li> <li>Sub-selector object filters provide an way to filter items from list properties.</li> <li>See sub-selectors for more information.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Improvements to PSRule engine API documentation by @BernieWhite.   #1186</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0039-pre-release","title":"v2.4.0-B0039 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0022:</p> <ul> <li>New features:<ul> <li>Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite.   #1227 #1016<ul> <li>Added conversion functions <code>boolean</code>, <code>string</code>, and <code>integer</code>.</li> <li>Added lookup functions <code>configuration</code>, and <code>path</code>.</li> <li>Added string functions <code>concat</code>, <code>substring</code>.</li> <li>See functions for more information.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite.   #1229<ul> <li>Added <code>Execution.DuplicateResourceId</code> option to configure PSRule behaviour.</li> <li>By default, duplicate resource identifiers return an error.</li> </ul> </li> <li>Fixed exception on JSON baseline without a synopsis by @BernieWhite.   #1230</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0022-pre-release","title":"v2.4.0-B0022 (pre-release)","text":"<p>What's changed since pre-release v2.4.0-B0009:</p> <ul> <li>Engineering:<ul> <li>Updates to PSRule engine API by @BernieWhite.   #1152<ul> <li>Added tool support for baselines parameter.</li> <li>Added module path discovery.</li> <li>Added output for verbose and debug messages.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v240-b0009-pre-release","title":"v2.4.0-B0009 (pre-release)","text":"<p>What's changed since v2.3.2:</p> <ul> <li>Engineering:<ul> <li>Bump support projects to .NET 6 by @BernieWhite.   #1209</li> <li>Bump Microsoft.NET.Test.Sdk to v17.3.0.   #1213</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed repository information not in output by @BernieWhite.   #1219</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v232","title":"v2.3.2","text":"<p>What's changed since v2.3.1:</p> <ul> <li>Bug fixes:<ul> <li>Fixes lost scope for rules by @BernieWhite.   #1214</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v231","title":"v2.3.1","text":"<p>What's changed since v2.3.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed object path join handling of self path identifier by @BernieWhite.   #1204</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230","title":"v2.3.0","text":"<p>What's changed since v2.2.0:</p> <ul> <li>General improvements:<ul> <li>Added <code>PathPrefix</code> method to add an object path prefix to assertion reasons by @BernieWhite.   #1198</li> <li>Added support for binding with JSON objects by @BernieWhite.   #1182</li> <li>Added support for full path from JSON objects by @BernieWhite.   #1174</li> <li>Improved reporting of full object path from pre-processed results by @BernieWhite.   #1169</li> <li>Added PSRule for Azure expansion configuration to options schema by @BernieWhite.   #1149</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit to v2.4.2.   #1200</li> <li>Expose online link extension method by @BernieWhite.   #1195</li> <li>Added comment documentation to .NET classes and interfaces by @BernieWhite.   #1186</li> <li>Added publishing support for NuGet symbol packages @BernieWhite.   #1173</li> <li>Updated outcome option docs by @BernieWhite.   #1166</li> <li>Bump Sarif.Sdk to v2.4.16.   #1177</li> <li>Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite.   #1152</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes JSON parsing of string array for single objects by @BernieWhite.   #1193</li> <li>Fixed handling for JSON objects in rules by @BernieWhite.   #1187</li> <li>Fixed null object reference for object equity comparison by @BernieWhite.   #1157</li> <li>Fixed expression evaluation not logging debug output when using the <code>-Debug</code> switch by @BernieWhite.   #1158</li> <li>Fixed startIndex cannot be larger than length of string by @BernieWhite.   #1160</li> <li>Fixed path within SDK package causes <code>psd1</code> to compile by @BernieWhite.   #1146</li> </ul> </li> </ul> <p>What's changed since pre-release v2.3.0-B0163:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0163-pre-release","title":"v2.3.0-B0163 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0130:</p> <ul> <li>General improvements:<ul> <li>Added <code>PathPrefix</code> method to add an object path prefix to assertion reasons by @BernieWhite.   #1198</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit to v2.4.2.   #1200</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0130-pre-release","title":"v2.3.0-B0130 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0100:</p> <ul> <li>Engineering:<ul> <li>Expose online link extension method by @BernieWhite.   #1195</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixes JSON parsing of string array for single objects by @BernieWhite.   #1193</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0100-pre-release","title":"v2.3.0-B0100 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0074:</p> <ul> <li>Engineering:<ul> <li>Added comment documentation to .NET classes and interfaces by @BernieWhite.   #1186</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed handling for JSON objects in rules by @BernieWhite.   #1187</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0074-pre-release","title":"v2.3.0-B0074 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0051:</p> <ul> <li>General improvements:<ul> <li>Added support for binding with JSON objects by @BernieWhite.   #1182</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0051-pre-release","title":"v2.3.0-B0051 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0030:</p> <ul> <li>General improvements:<ul> <li>Added support for full path from JSON objects by @BernieWhite.   #1174</li> </ul> </li> <li>Engineering:<ul> <li>Added publishing support for NuGet symbol packages @BernieWhite.   #1173</li> <li>Updated outcome option docs by @BernieWhite.   #1166</li> <li>Bump Sarif.Sdk to v2.4.16.   #1177</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0030-pre-release","title":"v2.3.0-B0030 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0015:</p> <ul> <li>General improvements:<ul> <li>Improved reporting of full object path from pre-processed results by @BernieWhite.   #1169</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0015-pre-release","title":"v2.3.0-B0015 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0006:</p> <ul> <li>Bug fixes:<ul> <li>Fixed null object reference for object equity comparison by @BernieWhite.   #1157</li> <li>Fixed expression evaluation not logging debug output when using the <code>-Debug</code> switch by @BernieWhite.   #1158</li> <li>Fixed startIndex cannot be larger than length of string by @BernieWhite.   #1160</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0006-pre-release","title":"v2.3.0-B0006 (pre-release)","text":"<p>What's changed since pre-release v2.3.0-B0001:</p> <ul> <li>General improvements:<ul> <li>Added PSRule for Azure expansion configuration to options schema by @BernieWhite.   #1149</li> </ul> </li> <li>Engineering:<ul> <li>Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite.   #1152</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v230-b0001-pre-release","title":"v2.3.0-B0001 (pre-release)","text":"<p>What's changed since v2.2.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed path within SDK package causes <code>psd1</code> to compile by @BernieWhite.   #1146</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220","title":"v2.2.0","text":"<p>What's changed since v2.1.0:</p> <ul> <li>New features:<ul> <li>Added <code>notCount</code> expression and assertion helper by @ArmaanMcleod.   #1091</li> </ul> </li> <li>General improvements:<ul> <li>Improved reporting of the object path that caused rule failures by @BernieWhite.   #1092<ul> <li>Output include a new <code>Detail</code> property with details of the reason and the object path.</li> <li>Custom methods <code>ReasonFrom</code> and <code>ReasonIf</code> accept a <code>path</code> parameter to specify the object path.</li> </ul> </li> <li>Added informational message when output has been written to disk by @BernieWhite.   #1074<ul> <li>The <code>Output.Footer</code> option now supports <code>OutputFile</code> which reports the output file path.   This is enabled by default.</li> </ul> </li> <li>Added descendant selector to object path syntax by @BernieWhite.   #1133<ul> <li>Use <code>..</code> to traverse into child objects, for example <code>$..name</code> finds names for all nested objects.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to 13.0.1.   #1137</li> <li>Added more object path tests by @ArmaanMcleod.   #1110</li> <li>Bump xunit.runner.visualstudio to 2.4.5.   #1084</li> <li>Bump Pester to 5.3.3.   #1079</li> <li>Bump Microsoft.NET.Test.Sdk to 17.2.0.   #1089</li> <li>Added NuGet packaging publishing by @BernieWhite.   #1093</li> <li>Updated NuGet packaging metadata by @BernieWhite.   #1093</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed output of reason with wide format by @BernieWhite.   #1117</li> <li>Fixed piped input does not respect excluded paths by @BernieWhite.   #1114<ul> <li>By default, objects are not excluded by source.</li> <li>To exclude piped input based on source configure the <code>Input.IgnoreObjectSource</code> option.</li> </ul> </li> <li>Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite.   #1140</li> <li>Fixed grouping of logical operators in object path by @BernieWhite.   #1101</li> </ul> </li> </ul> <p>What's changed since pre-release v2.2.0-B0175:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0175-pre-release","title":"v2.2.0-B0175 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0131:</p> <ul> <li>Bug fixes:<ul> <li>Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite.   #1140</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0131-pre-release","title":"v2.2.0-B0131 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0089:</p> <ul> <li>General improvements:<ul> <li>Added descendant selector to object path syntax by @BernieWhite.   #1133<ul> <li>Use <code>..</code> to traverse into child objects, for example <code>$..name</code> finds names for all nested objects.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Newtonsoft.Json to 13.0.1.   #1137</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0089-pre-release","title":"v2.2.0-B0089 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0052:</p> <ul> <li>General improvements:<ul> <li>Improved reporting of the object path that caused rule failures by @BernieWhite.   #1092<ul> <li>Output include a new <code>Detail</code> property with details of the reason and the object path.</li> <li>Custom methods <code>ReasonFrom</code> and <code>ReasonIf</code> accept a <code>path</code> parameter to specify the object path.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0052-pre-release","title":"v2.2.0-B0052 (pre-release)","text":"<p>What's changed since pre-release v2.2.0-B0021:</p> <ul> <li>General improvements:<ul> <li>Added informational message when output has been written to disk by @BernieWhite.   #1074<ul> <li>The <code>Output.Footer</code> option now supports <code>OutputFile</code> which reports the output file path.   This is enabled by default.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Added more object path tests by @ArmaanMcleod.   #1110</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed output of reason with wide format by @BernieWhite.   #1117</li> <li>Fixed piped input does not respect excluded paths by @BernieWhite.   #1114<ul> <li>By default, objects are not excluded by source.</li> <li>To exclude piped input based on source configure the <code>Input.IgnoreObjectSource</code> option.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v220-b0021-pre-release","title":"v2.2.0-B0021 (pre-release)","text":"<p>What's changed since v2.1.0:</p> <ul> <li>New features:<ul> <li>Added <code>notCount</code> expression and assertion helper by @ArmaanMcleod.   #1091</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit.runner.visualstudio to 2.4.5.   #1084</li> <li>Bump Pester to 5.3.3.   #1079</li> <li>Bump Microsoft.NET.Test.Sdk to 17.2.0.   #1089</li> <li>Added NuGet packaging publishing by @BernieWhite.   #1093</li> <li>Updated NuGet packaging metadata by @BernieWhite.   #1093</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed grouping of logical operators in object path by @BernieWhite.   #1101</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v210","title":"v2.1.0","text":"<p>What's changed since v2.0.1:</p> <ul> <li>General improvements:<ul> <li>Added <code>notStartsWith</code>, <code>notEndsWith</code>, and <code>notContains</code> expressions and assertion helpers. #1047</li> <li>Added <code>like</code>, <code>notLike</code> expressions and assertion helpers. #1048</li> <li>Added additional repository paths to ignore by default. #1043</li> <li>Added custom suppression message during PSRule runs. #1046<ul> <li>When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.</li> <li>Configure the suppression group synopsis to display a custom message.</li> <li>Suppression groups synopsis can be localized using markdown documentation.</li> <li>Use markdown to set a culture specific synopsis.</li> <li>Custom suppression messages are not supported when suppressing individual rules using <code>ps-rule.yaml</code>.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> <li>Added source support for string conditions. #1068</li> </ul> </li> <li>Engineering:<ul> <li>Added code signing of module. #1049</li> <li>Added SBOM manifests to module. #1050</li> <li>Bump Sarif.Sdk to 2.4.15. #1075</li> <li>Bump Pester to 5.3.2. #1062</li> </ul> </li> <li>Bug fixes:<ul> <li>Important change: Fixed source scope not updated in multi-module runs. #1053<ul> <li>Several properties of rule and language block elements have been renamed to improve consistency.</li> <li>From v3 custom scripts may not work correctly until you update these names.</li> <li>For details on the updated property names see deprecations.</li> </ul> </li> </ul> </li> </ul> <p>What's changed since pre-release v2.1.0-B0069:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v210-b0069-pre-release","title":"v2.1.0-B0069 (pre-release)","text":"<p>What's changed since pre-release v2.1.0-B0040:</p> <ul> <li>General improvements:<ul> <li>Added <code>notStartsWith</code>, <code>notEndsWith</code>, and <code>notContains</code> expressions and assertion helpers. #1047</li> <li>Added <code>like</code>, <code>notLike</code> expressions and assertion helpers. #1048</li> <li>Added additional repository paths to ignore by default. #1043</li> </ul> </li> <li>Engineering:<ul> <li>Bump Sarif.Sdk to 2.4.15. #1075</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v210-b0040-pre-release","title":"v2.1.0-B0040 (pre-release)","text":"<p>What's changed since pre-release v2.1.0-B0015:</p> <ul> <li>General improvements:<ul> <li>Added custom suppression message during PSRule runs. #1046<ul> <li>When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.</li> <li>Configure the suppression group synopsis to display a custom message.</li> <li>Suppression groups synopsis can be localized using markdown documentation.</li> <li>Use markdown to set a culture specific synopsis.</li> <li>Custom suppression messages are not supported when suppressing individual rules using <code>ps-rule.yaml</code>.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> <li>Added source support for string conditions. #1068</li> </ul> </li> <li>Engineering:<ul> <li>Bump Sarif.Sdk to 2.4.14. #1064</li> <li>Bump Pester to 5.3.2. #1062</li> </ul> </li> <li>Bug fixes:<ul> <li>Important change: Fixed source scope not updated in multi-module runs. #1053<ul> <li>Several properties of rule and language block elements have been renamed to improve consistency.</li> <li>From v3 custom scripts may not work correctly until you update these names.</li> <li>For details on the updated property names see deprecations.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v210-b0015-pre-release","title":"v2.1.0-B0015 (pre-release)","text":"<p>What's changed since v2.0.1:</p> <ul> <li>Engineering:<ul> <li>Added code signing of module. #1049</li> <li>Added SBOM manifests to module. #1050</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v201","title":"v2.0.1","text":"<p>What's changed since v2.0.0:</p> <ul> <li>Bug fixes:<ul> <li>Fixed read JSON failed with comments. #1051</li> <li>Fixed null reference on elapsed time when required module check fails. #1054</li> <li>Fixed failed to read JSON objects with a empty property name. #1052</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200","title":"v2.0.0","text":"<p>What's changed since v1.11.1:</p> <ul> <li>New features:<ul> <li>Add support for suppression groups. #793<ul> <li>New <code>SuppressionGroup</code> resource has been included.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> <li>Added source expression property. #933<ul> <li>Included the following expressions:<ul> <li><code>source</code></li> <li><code>withinPath</code></li> <li><code>notWithinPath</code></li> </ul> </li> </ul> </li> <li>Added support for rule severity level. #880<ul> <li>Rules can be configured to be <code>Error</code>, <code>Warning</code>, or <code>Information</code>.</li> <li>Failing rules with the <code>Error</code> severity level will cause the pipeline to fail.</li> <li>Rules with the <code>Warning</code> severity level will be reported as warnings.</li> <li>Rules with the <code>Information</code> severity level will be reported as informational messages.</li> <li>By default, the severity level for a rule is <code>Error</code>.</li> </ul> </li> <li>Added expression support for type based assertions. #908<ul> <li>Included the following expressions:<ul> <li><code>IsArray</code></li> <li><code>IsBoolean</code></li> <li><code>IsDateTime</code></li> <li><code>IsInteger</code></li> <li><code>IsNumeric</code></li> </ul> </li> </ul> </li> <li>Added support for formatting results as SARIF. #878<ul> <li>Set <code>Output.Format</code> to <code>Sarif</code> to output results in the SARIF format.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Add option to disable invariant culture warning. #899<ul> <li>Added <code>Execution.InvariantCultureWarning</code> option.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> <li>Added support for object path expressions. #808 #693<ul> <li>Inspired by JSONPath, object path expressions can be used to access nested objects.</li> <li>Array members can be filtered and enumerated using object path expressions.</li> <li>Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improve tracking of suppressed objects. #794<ul> <li>Added <code>Execution.SuppressedRuleWarning</code> option to output warning for suppressed rules.</li> </ul> </li> <li>Added support for rule aliases. #792<ul> <li>Aliases allow rules to be references by an alternative name.</li> <li>When renaming rules, add a rule alias to avoid breaking references to the old rule name.</li> <li>To specify an alias use the <code>-Alias</code> parameter or <code>alias</code> metadata property in YAML or JSON.</li> </ul> </li> <li>Added support for stable identifiers with rule refs. #881<ul> <li>A rule ref may be optionally be used to reference a rule.</li> <li>Rule refs should be:   stable, not changing between releases;   opaque, as opposed to being a human-readable string.   Stable and opaque refs ease web lookup and to help to avoid language difficulties.</li> <li>To specify a rule ref use the <code>-Ref</code> parameter or <code>ref</code> metadata property in YAML or JSON.</li> </ul> </li> <li>Added new properties for module lookup to SARIF results. #951</li> <li>Capture and output repository info in Assert-PSRule runs. #978<ul> <li>Added <code>Repository.Url</code> option set repository URL reported in output.</li> <li>Repository URL is detected automatically for GitHub Actions and Azure Pipelines.</li> <li>Added <code>RepositoryInfo</code> to <code>Output.Banner</code> option.</li> <li>Repository info is shown by default.</li> </ul> </li> <li>Added <code>convert</code> and <code>caseSensitive</code> to string comparison expressions. #1001<ul> <li>The following expressions support type conversion and case-sensitive comparison.<ul> <li><code>startsWith</code>, <code>contains</code>, and <code>endsWith</code>.</li> <li><code>equals</code> and <code>notEquals</code>.</li> </ul> </li> </ul> </li> <li>Added <code>convert</code> to numeric comparison expressions. #943<ul> <li>Type conversion is now supported for <code>less</code>, <code>lessOrEquals</code>, <code>greater</code>, and <code>greaterOrEquals</code>.</li> </ul> </li> <li>Added <code>Extent</code> property on rules reported by <code>Get-PSRule</code>. #990<ul> <li>Extent provides the line and position of the rule in the source code.</li> </ul> </li> <li>Breaking change: Added validation of resource names. #1012<ul> <li>Invalid rules names will now produce a specific error.</li> <li>See upgrade notes for more information.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removal of deprecated default baseline from module manifest. #755<ul> <li>Set the default module baseline using module configuration.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Require <code>apiVersion</code> on YAML and JSON to be specified. #648<ul> <li>Resources should use <code>github.com/microsoft/PSRule/v1</code> as the <code>apiVersion</code>.</li> <li>Resources that do not specify an <code>apiVersion</code> will be ignored.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Prefer module sources over loose files. #610<ul> <li>Module sources are discovered before loose files.</li> <li>Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Require rule sources from current working directory to be explicitly included. #760<ul> <li>From v2 onwards, <code>$PWD</code> is not included by default unless <code>-Path .</code> or <code>-Path $PWD</code> is explicitly specified.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Added more tests for JSON resources. #929</li> <li>Bump Sarif.Sdk to 2.4.13. #1007</li> <li>Bump PowerShellStandard.Library to 5.1.1. #999</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed object path handling with dash. #902</li> <li>Fixed empty suppression group rules property applies to no rules. #931</li> <li>Fixed object reference for suppression group will rule not defined. #932</li> <li>Fixed rule source loading twice from <code>$PWD</code> and <code>.ps-rule/</code>. #939</li> <li>Fixed rule references in SARIF format for extensions need a toolComponent reference. #949</li> <li>Fixed file objects processed with file input format have no source location. #950</li> <li>Fixed GitHub code scanning alerts treats pass as problems. #955<ul> <li>By default, SARIF output will only include fail or error outcomes.</li> <li>Added <code>Output.SarifProblemsOnly</code> option to include pass outcomes.</li> </ul> </li> <li>Fixed SARIF output includes rule property for default tool component. #956</li> <li>Fixed Invoke-PSRule hanging if JSON rule file is empty. #969</li> <li>Fixed SARIF should report base branch. #964</li> <li>Fixed unclear error message on invalid rule names. #1012</li> </ul> </li> </ul> <p>What's changed since pre-release v2.0.0-B2203045:</p> <ul> <li>No additional changes.</li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2203045-pre-release","title":"v2.0.0-B2203045 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2203033:</p> <ul> <li>General improvements:<ul> <li>Added <code>convert</code> to numeric comparison expressions. #943<ul> <li>Type conversion is now supported for <code>less</code>, <code>lessOrEquals</code>, <code>greater</code>, and <code>greaterOrEquals</code>.</li> </ul> </li> <li>Breaking change: Added validation of resource names. #1012<ul> <li>Invalid rules names will now produce a specific error.</li> <li>See upgrade notes for more information.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed unclear error message on invalid rule names. #1012</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2203033-pre-release","title":"v2.0.0-B2203033 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2203019:</p> <ul> <li>General improvements:<ul> <li>Added <code>Extent</code> property on rules reported by <code>Get-PSRule</code>. #990<ul> <li>Extent provides the line and position of the rule in the source code.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump Sarif.Sdk to 2.4.13. #1007</li> <li>Bump PowerShellStandard.Library to 5.1.1. #999</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2203019-pre-release","title":"v2.0.0-B2203019 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202072:</p> <ul> <li>General improvements:<ul> <li>Added <code>convert</code> and <code>caseSensitive</code> to string comparison expressions. #1001<ul> <li>The following expressions support type conversion and case-sensitive comparison.<ul> <li><code>startsWith</code>, <code>contains</code>, and <code>endsWith</code>.</li> <li><code>equals</code> and <code>notEquals</code>.</li> </ul> </li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202072-pre-release","title":"v2.0.0-B2202072 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202065:</p> <ul> <li>General improvements:<ul> <li>Capture and output repository info in Assert-PSRule runs. #978<ul> <li>Added <code>Repository.Url</code> option set repository URL reported in output.</li> <li>Repository URL is detected automatically for GitHub Actions and Azure Pipelines.</li> <li>Added <code>RepositoryInfo</code> to <code>Output.Banner</code> option.</li> <li>Repository info is shown by default.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed SARIF should report base branch. #964</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202065-pre-release","title":"v2.0.0-B2202065 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202056:</p> <ul> <li>Bug fixes:<ul> <li>Fixed broken documentation links. #980</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202056-pre-release","title":"v2.0.0-B2202056 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202024:</p> <ul> <li>Bug fixes:<ul> <li>Fixed Invoke-PSRule hanging if JSON rule file is empty. #969</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202024-pre-release","title":"v2.0.0-B2202024 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202017:</p> <ul> <li>New features:<ul> <li>Added source expression property. #933<ul> <li>Included the following expressions:<ul> <li><code>source</code></li> <li><code>withinPath</code></li> <li><code>notWithinPath</code></li> </ul> </li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202017-pre-release","title":"v2.0.0-B2202017 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2202006:</p> <ul> <li>Bug fixes:<ul> <li>Fixed GitHub code scanning alerts treats pass as problems. #955<ul> <li>By default, SARIF output will only include fail or error outcomes.</li> <li>Added <code>Output.SarifProblemsOnly</code> option to include pass outcomes.</li> </ul> </li> <li>Fixed SARIF output includes rule property for default tool component. #956</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2202006-pre-release","title":"v2.0.0-B2202006 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201161:</p> <ul> <li>General improvements:<ul> <li>Added new properties for module lookup to SARIF results. #951</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed rule references in SARIF format for extensions need a toolComponent reference. #949</li> <li>Fixed file objects processed with file input format have no source location. #950</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201161-pre-release","title":"v2.0.0-B2201161 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201146:</p> <ul> <li>New features:<ul> <li>Added support for rule severity level. #880<ul> <li>Rules can be configured to be <code>Error</code>, <code>Warning</code>, or <code>Information</code>.</li> <li>Failing rules with the <code>Error</code> severity level will cause the pipeline to fail.</li> <li>Rules with the <code>Warning</code> severity level will be reported as warnings.</li> <li>Rules with the <code>Information</code> severity level will be reported as informational messages.</li> <li>By default, the severity level for a rule is <code>Error</code>.</li> </ul> </li> <li>Added expression support for type based assertions. #908<ul> <li>Included the following expressions:<ul> <li><code>IsArray</code></li> <li><code>IsBoolean</code></li> <li><code>IsDateTime</code></li> <li><code>IsInteger</code></li> <li><code>IsNumeric</code></li> </ul> </li> </ul> </li> <li>Added support for formatting results as SARIF. #878<ul> <li>Set <code>Output.Format</code> to <code>Sarif</code> to output results in the SARIF format.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201146-pre-release","title":"v2.0.0-B2201146 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201135:</p> <ul> <li>Engineering:<ul> <li>Breaking change: Require rule sources from current working directory to be explicitly included. #760<ul> <li>From v2 onwards, <code>$PWD</code> is not included by default unless <code>-Path .</code> or <code>-Path $PWD</code> is explicitly specified.</li> <li>See upgrade notes for details.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed rule source loading twice from <code>$PWD</code> and <code>.ps-rule/</code>. #939</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201135-pre-release","title":"v2.0.0-B2201135 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201117:</p> <ul> <li>Engineering:<ul> <li>Breaking change: Prefer module sources over loose files. #610<ul> <li>Module sources are discovered before loose files.</li> <li>Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Added more tests for JSON resources. #929</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed empty suppression group rules property applies to no rules. #931</li> <li>Fixed object reference for suppression group will rule not defined. #932</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201117-pre-release","title":"v2.0.0-B2201117 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201093:</p> <ul> <li>General improvements:<ul> <li>Add option to disable invariant culture warning. #899<ul> <li>Added <code>Execution.InvariantCultureWarning</code> option.</li> <li>See about_PSRule_Options for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201093-pre-release","title":"v2.0.0-B2201093 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201075:</p> <ul> <li>New features:<ul> <li>Add support for suppression groups. #793<ul> <li>New <code>SuppressionGroup</code> resource has been included.</li> <li>See about_PSRule_SuppressionGroups for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201075-pre-release","title":"v2.0.0-B2201075 (pre-release)","text":"<p>What's changed since pre-release v2.0.0-B2201054:</p> <ul> <li>General improvements:<ul> <li>Added support for rule aliases. #792<ul> <li>Aliases allow rules to be references by an alternative name.</li> <li>When renaming rules, add a rule alias to avoid breaking references to the old rule name.</li> <li>To specify an alias use the <code>-Alias</code> parameter or <code>alias</code> metadata property in YAML or JSON.</li> </ul> </li> <li>Added support for stable identifiers with rule refs. #881<ul> <li>A rule ref may be optionally be used to reference a rule.</li> <li>Rule refs should be:   stable, not changing between releases;   opaque, as opposed to being a human-readable string.   Stable and opaque refs ease web lookup and to help to avoid language difficulties.</li> <li>To specify a rule ref use the <code>-Ref</code> parameter or <code>ref</code> metadata property in YAML or JSON.</li> </ul> </li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed object path handling with dash. #902</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v2/#v200-b2201054-pre-release","title":"v2.0.0-B2201054 (pre-release)","text":"<p>What's changed since v1.11.0:</p> <ul> <li>General improvements:<ul> <li>Added support for object path expressions. #808 #693<ul> <li>Inspired by JSONPath, object path expressions can be used to access nested objects.</li> <li>Array members can be filtered and enumerated using object path expressions.</li> <li>Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.</li> <li>See about_PSRule_Assert for details.</li> </ul> </li> <li>Improve tracking of suppressed objects. #794<ul> <li>Added <code>Execution.SuppressedRuleWarning</code> option to output warning for suppressed rules.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Removal of deprecated default baseline from module manifest. #755<ul> <li>Set the default module baseline using module configuration.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Require <code>apiVersion</code> on YAML and JSON to be specified. #648<ul> <li>Resources should use <code>github.com/microsoft/PSRule/v1</code> as the <code>apiVersion</code>.</li> <li>Resources that do not specify an <code>apiVersion</code> will be ignored.</li> <li>See upgrade notes for details.</li> </ul> </li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/","title":"Change log","text":"<p>See upgrade notes for helpful information when upgrading from previous versions.</p> <p>Experimental features:</p> <ul> <li>Baseline groups allow you to use a friendly name to reference baselines.   See baselines for more information.</li> <li>Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition.   See functions for more information.</li> <li>Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties.   See sub-selectors for more information.</li> <li> <p>Processing of changes files only within a pipeline.   See creating your pipeline for more information.</p> </li> </ul>"},{"location":"CHANGELOG-v3/#unreleased","title":"Unreleased","text":""},{"location":"CHANGELOG-v3/#v300-b0198-pre-release","title":"v3.0.0-B0198 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0153:</p> <ul> <li>Engineering:<ul> <li>Bump System.Drawing.Common to v8.0.5.   #1817</li> <li>Bump Bump xunit to v2.8.0.   #1809</li> <li>Bump xunit.runner.visualstudio to v2.8.0.   #1808</li> <li>Bump YamlDotNet to v15.1.4.   #1816</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.9.2.   #1773</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed discovery of installed modules in CLI by @BernieWhite.   #1779</li> <li>Fixed for git head in tests by @BernieWhite.   #1801</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0153-pre-release","title":"v3.0.0-B0153 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0151:</p> <ul> <li>Bug fixes:<ul> <li>Fixes null references for CLI module handling by @BernieWhite.   #1746</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0151-pre-release","title":"v3.0.0-B0151 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0141:</p> <ul> <li>General improvements:<ul> <li>Improved support for packaging with Visual Studio Code by @BernieWhite.   #1755</li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Bump development tools to .NET 8.0 SDK by @BernieWhite.   #1673<ul> <li>Running PSRule from PowerShell 7.x is supported on 7.4 and above.</li> <li>Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.</li> </ul> </li> <li>Bump Microsoft.NET.Test.Sdk to v17.9.0.   #1752</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed CLI null reference when include module is undefined by @BernieWhite.   #1746</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0141-pre-release","title":"v3.0.0-B0141 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0137:</p> <ul> <li>General improvements:<ul> <li>SARIF output has been improved to include effective configuration from a run by @BernieWhite.   #1739</li> <li>SARIF output has been improved to include file hashes for source files from a run by @BernieWhite.   #1740</li> <li>Added support to allow disabling PowerShell features that can be run from a repository by @BernieWhite.   #1742<ul> <li>Added the <code>Execution.RestrictScriptSource</code> option to disable running scripts from a repository.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump YamlDotNet to v15.1.0.   #1737</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0137-pre-release","title":"v3.0.0-B0137 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0122:</p> <ul> <li>General improvements:<ul> <li>Breaking change: Moved the <code>restore</code> command to a sub-command of <code>module</code> by @BernieWhite.   #1730<ul> <li>The functionality of the <code>restore</code> command is now available as <code>module restore</code>.</li> </ul> </li> <li>Added CLI commands to list and report status of locked modules by @BernieWhite.   #1729<ul> <li>Added <code>module init</code> sub-command to initialize the lock file from configured options.</li> <li>Added <code>module list</code> sub-command to list locked and unlocked modules associated with the workspace.</li> <li>Added <code>version</code> property to the lock file schema to support versioning of the lock file.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Bump BenchmarkDotNet to v0.13.12.   #1725</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.12.   #1728</li> <li>Bump xunit to v2.6.6.   #1732</li> <li>Bump xunit.runner.visualstudio to v2.5.6.   #1717</li> <li>Bump System.Drawing.Common to v8.0.1.   #1727</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0122-pre-release","title":"v3.0.0-B0122 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0093:</p> <ul> <li>General improvements:<ul> <li>Breaking change: Renamed <code>analyze</code> CLI command to <code>run</code> by @BernieWhite.   #1713</li> <li>Added <code>--outcome</code> argument for CLI to support filtering output by @bernieWhite.   #1706</li> </ul> </li> <li>Engineering:<ul> <li>Bump xunit to v2.6.3.   #1699</li> <li>Bump xunit.runner.visualstudio to v2.5.5.   #1700</li> <li>Bump Microsoft.NET.Test.Sdk to v17.8.0.   #1659</li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v8.0.0.   #1674</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.8.0.   #1686</li> <li>Bump BenchmarkDotNet to v0.13.11.   #1694</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.11.   #1697</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0093-pre-release","title":"v3.0.0-B0093 (pre-release)","text":"<p>What's changed since pre-release v3.0.0-B0084:</p> <ul> <li>Engineering:<ul> <li>Bump xunit to v2.6.1.   #1656</li> <li>Bump System.Drawing.Common to v8.0.0.   #1669</li> </ul> </li> <li>Bug fixes:<ul> <li>Fixed CLI IndexOutOfRangeException with lock file by @BernieWhite.   #1676</li> </ul> </li> </ul>"},{"location":"CHANGELOG-v3/#v300-b0084-pre-release","title":"v3.0.0-B0084 (pre-release)","text":"<p>What's changed since release v2.9.0:</p> <ul> <li>New features:<ul> <li>Added lock file support when using CLI and related tools by @BernieWhite.   #1660<ul> <li>The lock file used used during analysis and when installing modules to select a specific version.</li> </ul> </li> </ul> </li> <li>General improvements:<ul> <li>Breaking change: Switch to use SHA-512 for generating unbound objects by @BernieWhite.   #1155<ul> <li>Objects that have no bound name will automatically be assigned a name based on the SHA-512 hash of the object.</li> <li>Previously a SHA-1 hash was used, however this is no longer considered secure.</li> <li>The name for unbound objects that are suppressed will change as a result.</li> <li>Additionally the hash can be changed by setting the <code>Execution.HashAlgorithm</code> option.</li> <li>See upgrade notes for details.</li> </ul> </li> <li>Breaking change: Removed deprecated execution options by @BernieWhite.   #1457</li> <li>Breaking change: Removed deprecated object properties by @BernieWhite.   #1601</li> <li>Expanded support for <code>FileHeader</code> assertion by @BernieWhite.   #1521<ul> <li>Added support for <code>.bicepparam</code>, <code>.tsp</code>, <code>.tsx</code>, <code>.editorconfig</code>, <code>.ipynb</code>, and <code>.toml</code> files.</li> </ul> </li> </ul> </li> <li>Engineering:<ul> <li>Breaking change: Bump development tools to .NET 7.0 SDK by @BernieWhite.   #1631<ul> <li>Running PSRule from PowerShell 7.x is supported on 7.3 and above.</li> <li>Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.</li> </ul> </li> <li>Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.4.   #1602</li> <li>Bump Microsoft.CodeAnalysis.Common to v4.7.0.   #1593</li> <li>Bump Microsoft.NET.Test.Sdk to v17.7.2.   #1608</li> <li>Bump YamlDotNet to v13.7.1.   #1647</li> <li>Bump xunit to v2.5.3.   #1648</li> <li>Bump xunit.runner.visualstudio to v2.5.3.   #1644</li> <li>Bump BenchmarkDotNet to v0.13.10.   #1654</li> <li>Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.10.   #1654</li> </ul> </li> </ul>"},{"location":"about/","title":"What is PSRule?","text":"<p>PSRule is a rules engine geared towards testing Infrastructure as Code (IaC). Rules you write or import perform static analysis on IaC artifacts such as: templates, manifests, pipelines, and workflows.</p>"},{"location":"about/#why-use-psrule","title":"Why use PSRule?","text":"<p>PSRule aims to provide a rich experience for building and running static analysis tests on IaC. While this has some similarities to traditional testing frameworks it extends on the following:</p> <ul> <li>Reuse and share \u2014 existing pre-built rules, configure, or write your own.</li> <li>Incremental adoption \u2014 with baselines allows you to keep moving forward.</li> <li>Handle exceptions \u2014 and keep exceptions auditable in git history.</li> <li>Documentation \u2014 provides recommendations and examples instead of just pass or fail.</li> </ul>"},{"location":"addon-modules/","title":"Additional modules","text":""},{"location":"addon-modules/#integrations","title":"Integrations","text":""},{"location":"addon-modules/#azure-monitor","title":"Azure Monitor","text":"<p>You can send rule results to Azure Monitor using <code>PSRule.Monitor</code>.</p> <p></p>"},{"location":"addon-modules/#pre-built-rules","title":"Pre-built rules","text":"<p>The following modules contain pre-built rules that can be plugged into your pipeline.</p> Module Description Version / downloads PSRule.Rules.Azure A suite of rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements. PSRule.Monitor Log PSRule analysis results to Azure Monitor."},{"location":"analysis-output/","title":"Analysis output","text":"<p>PSRule supports generating and saving output in a number of different formats.</p> <p>Abstract</p> <p>This topic covers the supported formats and options for presenting output from a PSRule run.</p>"},{"location":"analysis-output/#setting-the-output-format","title":"Setting the output format","text":"<p>The output format can be configuring by setting the <code>Output.Format</code> option to one the following:</p> <ul> <li><code>Yaml</code> - Output is serialized as YAML.</li> <li><code>Json</code> - Output is serialized as JSON.</li> <li><code>Markdown</code> - Output is serialized as Markdown.</li> <li><code>NUnit3</code> - Output is serialized as NUnit3 (XML).</li> <li><code>Csv</code> - Output is serialized as a comma-separated values (CSV).</li> <li><code>Sarif</code> - Output is serialized as SARIF.</li> </ul> <p>Tip</p> <p>To write output to a file, also set the <code>Output.Path</code> option to the file path to save.</p> GitHub ActionsAzure PipelinesPowerShellOptions file <pre><code># Analyze and save results\n- name: Analyze repository\n  uses: microsoft/ps-rule@v2.9.0\n  with:\n    outputFormat: Sarif\n    outputPath: reports/ps-rule-results.sarif\n</code></pre> <pre><code># Analyze and save results\n- task: ps-rule-assert@2\n  displayName: Analyze repository\n  inputs:\n    inputType: repository\n    outputFormat: Sarif\n    outputPath: reports/ps-rule-results.sarif\n</code></pre> Invoke-PSRule<pre><code>Invoke-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n</code></pre> Assert-PSRule<pre><code>Assert-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n</code></pre> ps-rule.yaml<pre><code>output:\n  format: 'Sarif'\n  path: reports/ps-rule-results.sarif\n</code></pre>"},{"location":"analysis-output/#formatting-as-yaml","title":"Formatting as YAML","text":"<p>When using the YAML output format, results a serialized as YAML. Two spaces are used to indent properties of objects.</p> Example output <pre><code>- data: {}\n  info:\n    displayName: Local.PS.RequireTLS\n    name: Local.PS.RequireTLS\n    synopsis: An example rule to require TLS.\n  level: Error\n  outcome: Fail\n  outcomeReason: Processed\n  reason:\n  - The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\n  - The field 'configure.minTLSVersion' does not exist.\n  ruleName: Local.PS.RequireTLS\n  runId: 16b0534165ffb5279beeb1672a251fc1ff3124b6\n  source:\n  - file: C:\\Dev\\Workspace\\PSRule\\docs\\authoring\\writing-rules\\settings.json\n    line: 2\n    position: 11\n    type: File\n  targetName: 1fe7c0f476b11301402d5017d87424c36ff085a8\n  targetType: app1\n  time: 0\n</code></pre>"},{"location":"analysis-output/#formatting-as-json","title":"Formatting as JSON","text":"<p>When using the JSON output format, results are serialized as JSON. By default, no indentation is used.</p> Example output <pre><code>[{\"data\":{},\"info\":{\"displayName\":\"Local.PS.RequireTLS\",\"name\":\"Local.PS.RequireTLS\",\"synopsis\":\"An example rule to require TLS.\"},\"level\":1,\"outcome\":\"Fail\",\"outcomeReason\":\"Processed\",\"reason\":[\"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\"The field 'configure.minTLSVersion' does not exist.\"],\"ruleName\":\"Local.PS.RequireTLS\",\"runId\":\"df662aad3ae7adee6f35b9733c7aaa53dc4d6b96\",\"source\":[{\"file\":\"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\"line\":2,\"position\":11,\"type\":\"File\"}],\"targetName\":\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"targetType\":\"app1\",\"time\":0}]\n</code></pre>"},{"location":"analysis-output/#configuring-json-indentation","title":"Configuring JSON indentation","text":"<p> v1.8.0</p> <p>The number of spaces used to indent properties and elements is configurable between <code>0</code> to <code>4</code> spaces. By default, no indentation is used.</p> Example output with 2 spaces <pre><code>[\n  {\n    \"data\": {},\n    \"info\": {\n      \"displayName\": \"Local.PS.RequireTLS\",\n      \"name\": \"Local.PS.RequireTLS\",\n      \"synopsis\": \"An example rule to require TLS.\"\n    },\n    \"level\": 1,\n    \"outcome\": \"Fail\",\n    \"outcomeReason\": \"Processed\",\n    \"reason\": [\n      \"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\n      \"The field 'configure.minTLSVersion' does not exist.\"\n    ],\n    \"ruleName\": \"Local.PS.RequireTLS\",\n    \"runId\": \"3afadfed32e57f5283ad71c1aa496da822ff0c84\",\n    \"source\": [\n      {\n        \"file\": \"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\n        \"line\": 2,\n        \"position\": 11,\n        \"type\": \"File\"\n      }\n    ],\n    \"targetName\": \"1fe7c0f476b11301402d5017d87424c36ff085a8\",\n    \"targetType\": \"app1\",\n    \"time\": 0\n  }\n]\n</code></pre>"},{"location":"analysis-output/#formatting-as-csv","title":"Formatting as CSV","text":"<p>The output from analysis can be formatted as comma-separated values (CSV). Formatting as CSV may be useful when manipulating output results by hand. Output of CSV format varies depending on if detailed or summary output is used.</p> <p>For detailed output, the following columns are added to CSV output for each processed object:</p> Column Description <code>RuleName</code> The name of the rule. <code>TargetName</code> The name of the object that was analyzed. <code>TargetType</code> The type of the object that was analyzed. <code>Outcome</code> The outcome of the analysis, such as <code>Pass</code> or <code>Fail</code>. <code>OutcomeReason</code> An additional reason for the outcome such as <code>Inconclusive</code>. <code>Synopsis</code> A short description of the rule. <code>Recommendation</code> The recommendation of the rule. <p>For summary output, the following columns are used:</p> Column Description <code>RuleName</code> The name of the rule. <code>Pass</code> The number of objects that passed. <code>Fail</code> The number of objects that failed. <code>Outcome</code> The worst case outcome of the analysis, such as <code>Pass</code> or <code>Fail</code>. <code>Synopsis</code> A short description of the rule. <code>Recommendation</code> The recommendation of the rule. Example output <pre><code>RuleName,TargetName,TargetType,Outcome,OutcomeReason,Synopsis,Recommendation\n\"Local.PS.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.YAML.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.JSON.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n</code></pre>"},{"location":"analysis-output/#formatting-as-sarif","title":"Formatting as SARIF","text":"<p> v2.0.0</p> <p>Static Analysis Results Interchange Format (SARIF) is a standard output format for static analysis tools. It enables various unrelated tools to consume analysis results from PSRule. You can use SARIF to perform Static Analysis Security Testing (SAST) in DevOps environments at-scale.</p>"},{"location":"analysis-output/#github-code-scanning-alerts","title":"GitHub code scanning alerts","text":"<p>SARIF results from PSRule can be uploaded to GitHub to create code scanning alerts against a repository. You can see these results in your repository visible under Security &gt; Code scanning alerts.</p> <p>Tip</p> <p>Code scanning is available for all public repositories, and for private repositories owned by organizations where GitHub Advanced Security is enabled. For more information, see About GitHub Advanced Security.</p> <p>To configure GitHub Actions, perform the following steps:</p> <ul> <li>Create a GitHub Actions workflow.</li> <li>Add a step using the <code>microsoft/ps-rule</code> action.<ul> <li>Configure the <code>outputFormat</code> and <code>outputPath</code> parameters.</li> </ul> </li> <li>Add a step using the <code>github/codeql-action/upload-sarif</code> action.<ul> <li>Configure the <code>sarif_file</code> parameter to the same file path specified in <code>outputPath</code>.</li> </ul> </li> </ul> <p>Example <code>.github/workflows/analyze.yaml</code></p> <pre><code>name: Analyze\non:\n  push:\n    branches: [ main ]\n  schedule:\n  - cron: '24 22 * * 0' # At 10:24 PM, on Sunday each week\n  workflow_dispatch:\n\njobs:\n  oss:\n    name: Analyze with PSRule\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      security-events: write\n    steps:\n\n    - name: Checkout\n      uses: actions/checkout@v4\n\n    - name: Run PSRule analysis\n      uses: microsoft/ps-rule@v2.9.0\n      with:\n        outputFormat: Sarif\n        outputPath: reports/ps-rule-results.sarif\n\n    - name: Upload results to security tab\n      uses: github/codeql-action/upload-sarif@v3\n      with:\n        sarif_file: reports/ps-rule-results.sarif\n</code></pre>"},{"location":"analysis-output/#azure-devops-scans-tab","title":"Azure DevOps scans tab","text":"<p>SARIF results from PSRule can be uploaded and viewed within Azure DevOps. To add the scans tab to build results the SARIF SAST Scans Tab extension needs to be installed.</p>"},{"location":"analysis-output/#verifying-configuration","title":"Verifying configuration","text":"<p> v3.0.0</p> <p>The configuration used to run PSRule is included in properties of the run. This can be used to verify the configuration used to run PSRule.</p>"},{"location":"creating-your-pipeline/","title":"Creating your pipeline","text":"<p>You can use PSRule to test Infrastructure as Code (IaC) artifacts throughout their lifecycle. By using validation within a continuous integration (CI) pipeline, any issues provide fast feedback.</p> <p>Within the root directory of your IaC repository:</p> GitHub ActionsAzure PipelinesGeneric with PowerShell <p>Create a new GitHub Actions workflow by creating <code>.github/workflows/analyze-arm.yaml</code>.</p> <pre><code>name: Analyze templates\non:\n- pull_request\njobs:\n  analyze_arm:\n    name: Analyze templates\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: Checkout\n      uses: actions/checkout@v4\n\n    # Analyze Azure resources using PSRule for Azure\n    - name: Analyze Azure template files\n      uses: microsoft/ps-rule@v2.9.0\n      with:\n        modules: 'PSRule.Rules.Azure'\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p> <p>Create a new Azure DevOps YAML pipeline by creating <code>.azure-pipelines/analyze-arm.yaml</code>.</p> <pre><code>steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n  displayName: Analyze Azure template files\n  inputs:\n    inputType: repository\n    modules: 'PSRule.Rules.Azure'\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p> <p>Create a pipeline in any CI environment by using PowerShell.</p> <pre><code>$modules = @('PSRule.Rules.Azure')\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\n</code></pre> <p>Tip</p> <p>This example demonstrates using PSRule for Azure, a populate module for testing Azure IaC. Instead, you can write your own module or use one of our pre-built modules.</p>"},{"location":"creating-your-pipeline/#configuration","title":"Configuration","text":"<p>Configuration options for PSRule are set within the <code>ps-rule.yaml</code> file.</p>"},{"location":"creating-your-pipeline/#ignoring-rules","title":"Ignoring rules","text":"<p>To prevent a rule executing you can either:</p> <ul> <li>Exclude rules by name \u2014 The rule is not executed for any object.</li> <li>Suppress rules by name \u2014 The rule is not executed for a specific object by name.</li> <li>Suppress rules by condition \u2014 The rule is not executed for matching objects.</li> </ul> Exclude by nameSuppression by nameSuppression by condition <p>To exclude a rule, set <code>Rule.Exclude</code> option within the <code>ps-rule.yaml</code> file.</p> <p>[ Docs][3]</p> ps-rule.yaml<pre><code>rule:\n  exclude:\n  # Ignore the following rules for all objects\n  - Azure.VM.UseHybridUseBenefit\n  - Azure.VM.Standalone\n</code></pre> <p>To suppress an individual rule, set <code>Suppression</code> option within the <code>ps-rule.yaml</code> file.</p> <p>[ Docs][4]</p> ps-rule.yaml<pre><code>suppression:\n  Azure.AKS.AuthorizedIPs:\n  # Exclude the following externally managed AKS clusters\n  - aks-cluster-prod-eus-001\n  Azure.Storage.SoftDelete:\n  # Exclude the following non-production storage accounts\n  - storagedeveus6jo36t\n  - storagedeveus1df278\n</code></pre> <p>To suppress an rules by condition, create a suppression group.</p> <p>[ Docs][5]</p> <pre><code>---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: SuppressWithTargetName\nspec:\n  rule:\n  - 'FromFile1'\n  - 'FromFile2'\n  if:\n    name: '.'\n    in:\n    - 'TestObject1'\n    - 'TestObject2'\n</code></pre> <p>Tip</p> <p>Use comments within <code>ps-rule.yaml</code> to describe the reason why rules are excluded or suppressed. Meaningful comments help during peer review within a Pull Request (PR). Also consider including a date if the exclusions or suppressions are temporary.</p>"},{"location":"creating-your-pipeline/#processing-changed-files-only","title":"Processing changed files only","text":"<p> v2.5.0 \u00b7  Docs</p> <p>To only process files that have changed within a pull request, set the <code>Input.IgnoreUnchangedPath</code> option.</p> GitHub ActionsAzure PipelinesGeneric with PowerShell <p>Update your GitHub Actions workflow by setting the <code>PSRULE_INPUT_IGNOREUNCHANGEDPATH</code> environment variable.</p> .github/workflows/analyze-arm.yaml<pre><code>name: Analyze templates\non:\n- pull_request\njobs:\n  analyze_arm:\n    name: Analyze templates\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: Checkout\n      uses: actions/checkout@v4\n\n    # Analyze Azure resources using PSRule for Azure\n    - name: Analyze Azure template files\n      uses: microsoft/ps-rule@v2.9.0\n      with:\n        modules: 'PSRule.Rules.Azure'\n      env:\n        PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n</code></pre> <p>Update your Azure DevOps YAML pipeline by setting the <code>PSRULE_INPUT_IGNOREUNCHANGEDPATH</code> environment variable.</p> .azure-pipelines/analyze-arm.yaml<pre><code>steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n  displayName: Analyze Azure template files\n  inputs:\n    inputType: repository\n    modules: 'PSRule.Rules.Azure'\n  env:\n    PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n</code></pre> <p>Update your PowerShell command-line to include the <code>Input.IgnoreUnchangedPath</code> option.</p> PowerShell<pre><code>$modules = @('PSRule.Rules.Azure')\n$options = @{\n    'Input.IgnoreUnchangedPath' = $True\n}\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -Options $options -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\n</code></pre> <p>Tip</p> <p>In some cases it may be necessary to set <code>Repository.BaseRef</code> to the default branch of your repository. By default, PSRule will detect the default branch of the repository from the build system environment variables.</p>"},{"location":"deprecations/","title":"Deprecations","text":""},{"location":"deprecations/#deprecations-for-v3","title":"Deprecations for v3","text":""},{"location":"deprecations/#execution-options","title":"Execution options","text":"<p>PSRule provides a number of execution options that control logging of certain events. In many cases these options turn a warning on or off.</p> <p>These options are deprecated but replaced to provide more choice to when configuring logging options. Now you can configure the following:</p> <ul> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>The following execution options have been deprecated and will be removed from v3.</p> <ul> <li><code>Execution.SuppressedRuleWarning</code> is replaced with <code>Execution.RuleSuppressed</code>.   Set <code>Execution.RuleSuppressed</code> to <code>Warn</code> to log a warning from v2.8.0.   If both options are set, <code>Execution.SuppressedRuleWarning</code> takes precedence until v3.</li> <li><code>Execution.AliasReferenceWarning</code> is replaced with <code>Execution.AliasReference</code>.   Set <code>Execution.AliasReference</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.AliasReferenceWarning</code> takes precedence until v3.</li> <li><code>Execution.InconclusiveWarning</code> is replaced with <code>Execution.RuleInconclusive</code>.   Set <code>Execution.RuleInconclusive</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.InconclusiveWarning</code> takes precedence until v3.</li> <li><code>Execution.InvariantCultureWarning</code> is replaced with <code>Execution.InvariantCulture</code>.   Set <code>Execution.InvariantCulture</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.InvariantCultureWarning</code> takes precedence until v3.</li> <li><code>Execution.NotProcessedWarning</code> is replaced with <code>Execution.UnprocessedObject</code>.   Set <code>Execution.UnprocessedObject</code> to <code>Warn</code> to log a warning from v2.9.0.   If both options are set, <code>Execution.NotProcessedWarning</code> takes precedence until v3.</li> </ul> <p>Tip</p> <p>You do not need to configure both options. If you have the deprecated option configured, switch to the new option.</p>"},{"location":"deprecations/#git-head-input-object","title":"Git Head input object","text":"<p>Previously when the <code>Input.Format</code> option was set to <code>File</code> the <code>.git/HEAD</code> file was emitted as an input object. The original purpose of this feature was to allow conventions to run once against the root of the repository. Subsequent changes to PSRule have made this feature redundant by adding support for the <code>-Initialize</code> block.</p> <p>From v3 the <code>.git/HEAD</code> file will no longer be emitted as an input object.</p> <p>Consider adding or updating a convention that uses the <code>-Initialize</code> block to emit run initialization logic. Yon can also use the <code>-Initialize</code> block to emit a custom object to the pipeline by using the <code>$PSRule.ImportWithType</code> method.</p>"},{"location":"deprecations/#rule-output-object","title":"Rule output object","text":"<p>Several properties of the rule object have been renamed to improve consistency with other objects. Previously rules returned by <code>Get-PSRule</code> returned a rule object which included the following properties:</p> <ul> <li><code>RuleId</code></li> <li><code>RuleName</code></li> <li><code>Description</code></li> <li><code>ModuleName</code></li> <li><code>SourcePath</code></li> </ul> <p>These have been replaced with the following properties:</p> <ul> <li><code>Id</code> instead of <code>RuleId</code>.</li> <li><code>Name</code> instead of <code>RuleName</code>.</li> <li><code>Synopsis</code> instead of <code>Description</code>.</li> <li><code>Source.Module</code> instead of <code>ModuleName</code>.</li> <li><code>Source.Path</code> instead of <code>SourcePath</code>.</li> </ul> <p>The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.</p>"},{"location":"deprecations/#language-block-interface","title":"Language block interface","text":"<p>Several properties of Baselines and Selectors have been renamed to improve consistency.</p> <ul> <li><code>ModuleName</code></li> <li><code>SourcePath</code></li> </ul> <p>These have been replaced with the following properties:</p> <ul> <li><code>Source.Module</code> instead of <code>ModuleName</code>.</li> <li><code>Source.Path</code> instead of <code>SourcePath</code>.</li> </ul> <p>The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.</p>"},{"location":"deprecations/#deprecations-for-v2","title":"Deprecations for v2","text":""},{"location":"deprecations/#default-baseline-by-module-manifest","title":"Default baseline by module manifest","text":"<p>When packaging baselines in a module, you may want to specify a default baseline. PSRule v1.9.0 added support for setting the default baseline in a module configuration.</p> <p>Previously a default baseline could be set by specifying the baseline in the module manifest. From v1.9.0 this is deprecated and will be removed from v2.</p> <p>For details on how to migrate to the new default baseline option, continue reading the upgrade notes.</p>"},{"location":"deprecations/#resources-without-an-api-version","title":"Resources without an API version","text":"<p>When creating YAML and JSON resources you define a resource by specifying the <code>apiVersion</code> and <code>kind</code>. To allow new schema versions for resources to be introduced in the future, an <code>apiVersion</code> was introduced. For backwards compatibility, resources without an <code>apiVersion</code> deprecated but supported. From v2 resources without an <code>apiVersion</code> will be ignored.</p> <p>For details on how to add an <code>apiVersion</code> to a resource, continue reading the upgrade notes.</p>"},{"location":"faq/","title":"Frequently Asked Questions (FAQ)","text":""},{"location":"faq/#how-is-psrule-different-to-pester","title":"How is PSRule different to Pester?","text":"<p>PSRule is a framework for testing infrastructure as code (IaC) and objects using rules. Rules can be written in PowerShell, YAML, or JSON. Some features include:</p> <ul> <li>Objects - PowerShell objects can be validated on the pipeline or imported.<ul> <li>Objects can be imported directly from <code>JSON</code>, <code>YAML</code>, or <code>.psd1</code>.</li> <li>Each object is automatically bound to a target type for use with pre-conditions.</li> <li>Rule results are orientated to validating an object.</li> <li>Built-in assertions, automatically traverse object properties.</li> </ul> </li> <li>Pre-conditions - Rules understand which objects they apply to. Objects are bound to a type as they are processed using object properties. Dissimilar objects can be processed quickly.<ul> <li>Objects that match no rules are flagged with a warning by default.</li> </ul> </li> <li>Packaging - Rules can be reused between projects and optionally packaged into a module.<ul> <li>Portable rules, configuration, baselines, and documentation allow greater reuse and distribution.</li> <li>Documentation with detailed guidance or next steps can be included.</li> <li>Standalone or rules from modules can be combined together with <code>-Module</code> and <code>-Path</code>.</li> </ul> </li> <li>Configuration - Configuration of rules is handled by PSRule.<ul> <li>Rules can be configured at runtime, from YAML configuration, or environment variables.</li> <li>Baselines can be used to pair rules and configuration for a specific scenario.</li> </ul> </li> <li>Exceptions - Exceptions to a rule can be ignored for a single object using suppression.<ul> <li>Exclusion can be used additionally to ignore a rule entirely.</li> </ul> </li> </ul> <p>These features make PSRule ideal for validating:</p> <ul> <li>Infrastructure as code, including:<ul> <li>Kubernetes manifests.</li> <li>Azure Resource Manager (ARM) templates.</li> <li>Configuration files.</li> <li>Pipeline files.</li> </ul> </li> <li>Deployments or configurations against a baseline.</li> </ul> <p>If you want to test PowerShell code, consider using Pester, we do!</p>"},{"location":"faq/#what-pre-built-modules-are-available-for-psrule","title":"What pre-built modules are available for PSRule?","text":"<p>PSRule rules modules can be found on the PowerShell Gallery using the tag <code>PSRule-rules</code>.</p>"},{"location":"faq/#how-do-i-configure-psrule","title":"How do I configure PSRule?","text":"<p>PSRule and rules can be configured by:</p> <ul> <li>Parameter - PSRule can be configured at runtime by passing the <code>-Option</code> parameter to cmdlets.</li> <li>Options file - Options stored in YAML are load configuration from file. The default <code>ps-rule.yaml</code> option file is read automatically from the current working path by default. When checking into source control, store this file in the root directory of the repository.</li> <li>Environment variables - Configuration can be specified using environment variables.</li> </ul> <p>For example:</p> <pre><code># With cmdlet\n$option = New-PSRuleOption -OutputAs Summary -OutputCulture 'en-AU' -ExecutionUnprocessedObject 'Ignore' -Configuration @{\n  CUSTOM_VALUE = 'example'\n}\n$items | Assert-PSRule -Option $option\n\n# With hashtable\n$items | Assert-PSRule -Option @{\n  'Output.As' = 'Summary'\n  'Output.Culture' = 'en-AU'\n  'Execution.UnprocessedObject' = 'Ignore'\n  'Configuration.CUSTOM_VALUE' = 'Example'\n}\n</code></pre> <pre><code># With YAML\noutput:\n  as: Summary\n  culture: [ 'en-AU' ]\n\nexecution:\n  unprocessedObject: Ignore\n\nconfiguration:\n  CUSTOM_VALUE: Example\n</code></pre> <pre><code># With environment variable in bash\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\nexport PSRULE_OUTPUT_AS=Summary\nexport PSRULE_OUTPUT_CULTURE=en-AU\nexport PSRULE_CONFIGURATION_CUSTOM_VALUE=Example\n</code></pre> <p>For a list of configuration options and usage see about_PSRule_Options.</p>"},{"location":"faq/#how-do-i-ignore-a-rule","title":"How do I ignore a rule?","text":"<p>To prevent a rule executing you can either:</p> <ul> <li>Exclude the rule - The rule is not executed for any object.</li> <li>Suppress the rule - The rule is not executed for a specific object by name.</li> </ul> <p>To exclude a rule use the <code>Rule.Exclude</code> option. To do this in YAML, add the following to the <code>ps-rule.yaml</code> options file.</p> <pre><code># YAML: Using the rule/exclude property\nrule:\n  exclude:\n  - 'My.FirstRule'  # The name of the first rule to exclude.\n  - 'My.SecondRule' # The name of the second rule to exclude.\n</code></pre> <p>To suppress a rule use the <code>Suppression</code> option. To do this in YAML, add the following to the <code>ps-rule.yaml</code> options file.</p> <pre><code># YAML: Using the suppression property\nsuppression:\n  My.FirstRule:    # The name of the rule being suppressed\n  - TestObject1    # The name of the first object to suppress\n  - TestObject3    # The name of the second object to suppress\n  My.SecondRule:   # An additional rule to suppress\n  - TestObject2\n</code></pre> <p>The name of the object is reported by PSRule in output results.</p> <p>See about_PSRule_Options for additional usage for both of these options.</p>"},{"location":"faq/#how-do-exclude-or-ignore-files-from-being-processed","title":"How do exclude or ignore files from being processed?","text":"<p>To exclude or ignore files from being processed, configure the Input.PathIgnore option. This option allows you to ignore files using a path spec.</p> <p>For example:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude files with these extensions\n  - '*.md'\n  - '*.png'\n  # Exclude specific configuration files\n  - 'bicepconfig.json'\n</code></pre> <p>Or:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude all files\n  - '*'\n  # Only process deploy.bicep files\n  - '!**/deploy.bicep'\n</code></pre>"},{"location":"faq/#how-do-i-disable-or-suppress-the-not-processed-warning","title":"How do I disable or suppress the not processed warning?","text":"<p>You may receive a warning message suggesting a file or object has not been processed. If there are no rules that apply to the file or object this warning will be displayed.</p> <p>Note</p> <p>This warning is intended as a verification so that you are able to confirm your configuration is correct.</p> <p>After you have tuned your configuration, you may wish to disable this warning to reduce output noise. To do this you have two options:</p> <ol> <li>Exclude files from analysis \u2014 Configure the Input.PathIgnore option.</li> <li> <p>Disable the warning entirely \u2014 Set the Execution.UnprocessedObject option to <code>Ignore</code>.</p> </li> </ol>"},{"location":"faq/#how-do-i-layer-on-custom-rules-on-top-of-an-existing-module","title":"How do I layer on custom rules on top of an existing module?","text":"<p>PSRule allows rules from modules and standalone (loose) rules to be run together.</p> <p>To run rules from a standalone path use:</p> <pre><code># Note: .ps-rule/ is a standard path to include standalone rules.\n\n# With input from the pipeline\n$items | Assert-PSRule -Path '.ps-rule/'\n\n# With input from file\nAssert-PSRule -Path '.ps-rule/' -InputPath 'src/'\n</code></pre> <p>To run rules from an installed module use:</p> <pre><code># With input from the pipeline\n$items | Assert-PSRule -Module 'PSRule.Rules.Azure'\n\n# With input from file\nAssert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'src/'\n</code></pre> <p>Combining both:</p> <pre><code>Assert-PSRule -Module 'PSRule.Rules.Azure', 'PSRule.Rules.CAF' -Path '.ps-rule/' -InputPath 'src/'\n</code></pre>"},{"location":"faq/#why-should-i-use-psrule-keywords-and-assertions","title":"Why should I use PSRule keywords and assertions?","text":"<p>Except for the <code>Rule</code> keyword, using the built-in language features are optional.</p> <p>The built-in keywords and assertions accelerate rule creation. They do this by providing a condition and a set of reasons in a single command.</p> <p>Reasons are also optional; however, they provide additional context as to why the rule failed. Alternatively, you can provide your own reasons to complement standard PowerShell with the <code>Reason</code> keyword.</p>"},{"location":"faq/#collection-of-telemetry","title":"Collection of telemetry","text":"<p>PSRule currently does not collect any telemetry during installation or execution.</p> <p>PowerShell (used by PSRule) does collect basic telemetry by default. Collection of telemetry in PowerShell and how to opt-out is explained in about_Telemetry.</p>"},{"location":"features/","title":"Features","text":""},{"location":"features/#devops","title":"DevOps","text":"<p>PSRule allows you to quickly plug-in Infrastructure as Code (IaC) controls into your DevOps pipeline.</p> <ul> <li>Shift-left \u2014 Identify configuration issues and provide fast feedback in PRs.</li> <li>Quality gates \u2014 Implement quality gates between environments such as dev, test, and prod.</li> <li>Monitor continuously \u2014 Perform ongoing checks for configuration optimization opportunities.</li> </ul> <p>Run on MacOS, Linux, and Windows or anywhere PowerShell is supported. Native support for popular continuous integration (CI) systems includes:</p> <ul> <li>GitHub Actions \u2014 Trigger tests for GitHub repositories using workflows.</li> <li>Azure Pipelines \u2014 Use tasks to run tests in Azure DevOps YAML or Classic pipelines and releases.</li> </ul>"},{"location":"features/#extensible","title":"Extensible","text":"<p>Import pre-built rules or define your own using YAML, JSON, or PowerShell format. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.</p> <ul> <li>YAML \u2014 Use a popular, easy to read, and learn IaC format.   With YAML, you can quickly build out common rules with minimal effort and no scripting experience.</li> <li>JSON \u2014 Is ubiquitous, used by many tools.   While this format is typically harder to read then YAML it is easy to automate.   You may prefer to use this format if you are generating rules with automation.</li> <li>PowerShell \u2014 Is a flexible scripting language.   If you or your team already can write a basic PowerShell script, you can already define a rule.   PowerShell allows you to tap into a large world-wide community of PowerShell users.   Use existing cmdlets to help you build out rules quickly.</li> </ul> <p>Rules can be authored using any text editor, but we provide a native extension for Visual Studio Code. Use the extension to quickly author rules or run tests locally before you commit your IaC.</p>"},{"location":"features/#reusable","title":"Reusable","text":"<p>Typically unit tests in traditional testing frameworks are written for a specific case. This makes it hard invest in tests that are not easily reusable between projects. Several features of PSRule make it easier to reuse and share rules across teams or organizations.</p> <p>The following built-in features improve portability:</p> <ul> <li>Modular \u2014 Rules can be packages up into a standard PowerShell module then distributed.<ul> <li>Private \u2014 Modules can be published privately on a network share or NuGet feed.</li> <li>Public \u2014 Distribute rules globally using the PowerShell Gallery.</li> </ul> </li> <li>Configuration \u2014 PSRule and rules can be configured.</li> <li>Baselines \u2014 An artifact containing rules and configuration for a scenario.</li> <li>Suppression \u2014 Allows you to handle and keep exceptions auditable in git history.<ul> <li>Approval \u2014 Use code owners and branch policy concepts to control changes.</li> </ul> </li> <li> <p>Documentation \u2014 Provide guidance on how to resolve detected issues.</p> <ul> <li>Quick \u2014 Use a one liner to quickly add a hint or reference on rules you build.</li> <li>Detailed \u2014 Support for markdown allows you to provide detailed detailed guidance to resolve issues.</li> </ul> </li> </ul>"},{"location":"install/","title":"Install PSRule","text":"<p>PSRule supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates.</p> Task Options Run tests within CI pipelines With GitHub Actions or Azure Pipelines or CLI or PowerShell Run tests locally during development With Visual Studio Code and CLI / PowerShell Create custom tests for your organization With Visual Studio Code and CLI / PowerShell <p>Tip</p> <p>PSRule provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines. If you are using a different CI system you can use the local install to run on MacOS, Linux, and Windows worker nodes.</p>"},{"location":"install/#with-github-actions","title":"With GitHub Actions","text":"<p> GitHub Action</p> <p>Install and use PSRule with GitHub Actions by referencing the <code>microsoft/ps-rule</code> action.</p> Specific versionLatest stable v2Latest stable GitHub Actions<pre><code>- name: Analyze with PSRule\n  uses: microsoft/ps-rule@v2.9.0\n</code></pre> GitHub Actions<pre><code>- name: Analyze with PSRule\n  uses: microsoft/ps-rule@v2\n</code></pre> GitHub Actions<pre><code>- name: Analyze with PSRule\n  uses: microsoft/ps-rule@latest\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p> <p>Tip</p> <p>The recommended approach is to pin to the latest specific version. Pinning to a specific version reduces the risk of new versions breaking your pipeline. You can easily update to the latest version by changing the version number. At such time, you can test the new version in a feature branch before merging to main.</p>"},{"location":"install/#working-with-dependabot","title":"Working with Dependabot","text":"<p>You can use Dependabot to automatically upgrade your PSRule action if you use a specific version. When new versions a released Dependabot will automatically add a pull request (PR) for you to review and merge.</p> .github/dependabot.yaml<pre><code>#\n# Dependabot configuration\n#\nversion: 2\nupdates:\n\n  # Maintain GitHub Actions\n  - package-ecosystem: github-actions\n    directory: \"/\"\n    schedule:\n      interval: daily\n</code></pre>"},{"location":"install/#with-azure-pipelines","title":"With Azure Pipelines","text":"<p> Extension</p> <p>Install and use PSRule with Azure Pipeline by using extension tasks. Install the extension from the marketplace, then use the <code>ps-rule-assert</code> task in pipeline steps.</p> <pre><code>- task: ps-rule-assert@2\n  displayName: Analyze Azure template files\n  inputs:\n    inputType: repository\n</code></pre> <p>This will automatically install compatible versions of all dependencies.</p>"},{"location":"install/#with-visual-studio-code","title":"With Visual Studio Code","text":"<p> Extension</p> <p>An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in tasks and configuration schemas for working with PSRule.</p> <p> </p>"},{"location":"install/#with-cli","title":"With CLI","text":"<p>PSRule can be installed from NuGet.org using the .NET CLI where the .NET 8.0 SDK is available. You can use this option to install on CI workers that are not natively supported.</p> <p>To install PSRule as a global tool use the following command line:</p> <pre><code>dotnet tool install -g Microsoft.PSRule.Tool\n</code></pre> <p>To install a specific version use the following command line:</p> <pre><code>dotnet tool install -g Microsoft.PSRule.Tool --version 3.0.0-B0151\n</code></pre> <p>For a list of commands supported by the CLI, see PSRule CLI.</p>"},{"location":"install/#with-powershell","title":"With PowerShell","text":"<p>PSRule can be installed locally from the PowerShell Gallery using PowerShell. You can use this option to install on CI workers that are not natively supported.</p>"},{"location":"install/#prerequisites","title":"Prerequisites","text":"Operating System Tool Installation Link Windows Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater. link Windows, MacOS, Linux PowerShell version 7.4.x or greater. link <p>Note</p> <p>If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.</p>"},{"location":"install/#installing-powershell","title":"Installing PowerShell","text":"<p>PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default. For a list of platforms that PowerShell 7.4 is supported on and install instructions see Get PowerShell.</p>"},{"location":"install/#getting-the-modules","title":"Getting the modules","text":"<p> Module</p> <p>PSRule can be installed or updated from the PowerShell Gallery. Use the following command line examples from a PowerShell terminal to install or update PSRule.</p> For the current userFor all users <p>To install PSRule for the current user use:</p> <pre><code>Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\n</code></pre> <p>To update PSRule for the current user use:</p> <pre><code>Update-Module -Name 'PSRule' -Scope CurrentUser\n</code></pre> <p>Open PowerShell with Run as administrator on Windows or <code>sudo pwsh</code> on Linux.</p> <p>To install PSRule for all users (requires admin/ root permissions) use:</p> <pre><code>Install-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers\n</code></pre> <p>To update PSRule for all users (requires admin/ root permissions) use:</p> <pre><code>Update-Module -Name 'PSRule' -Scope AllUsers\n</code></pre>"},{"location":"install/#pre-release-versions","title":"Pre-release versions","text":"<p>To use a pre-release version of PSRule add the <code>-AllowPrerelease</code> switch when calling <code>Install-Module</code>, <code>Update-Module</code>, or <code>Save-Module</code> cmdlets.</p> <p>Tip</p> <p>To install pre-release module versions, the latest version of PowerShellGet may be required.</p> <pre><code># Install the latest PowerShellGet version\nInstall-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\n</code></pre> For the current userFor all users <p>To install PSRule for the current user use:</p> <pre><code>Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser -AllowPrerelease\n</code></pre> <p>Open PowerShell with Run as administrator on Windows or <code>sudo pwsh</code> on Linux.</p> <p>To install PSRule for all users (requires admin/ root permissions) use:</p> <pre><code>Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers -AllowPrerelease\n</code></pre>"},{"location":"install/#building-from-source","title":"Building from source","text":"<p> Source</p> <p>PSRule is provided as open source on GitHub. To build PSRule from source code:</p> <ol> <li>Clone the GitHub repository.</li> <li>Run <code>./build.ps1</code> from a PowerShell terminal in the cloned path.</li> </ol> <p>This build script will compile the module and documentation then output the result into <code>out/modules/PSRule</code>.</p>"},{"location":"install/#development-dependencies","title":"Development dependencies","text":"<p>The following PowerShell modules will be automatically install if the required versions are not present:</p> <ul> <li>PlatyPS</li> <li>Pester</li> <li>PSScriptAnalyzer</li> <li>PowerShellGet</li> <li>PackageManagement</li> <li>InvokeBuild</li> </ul> <p>These additional modules are only required for building PSRule.</p> <p>Additionally .NET SDK v8 is required. .NET will not be automatically downloaded and installed. To download and install the latest SDK see Download .NET 8.0.</p>"},{"location":"install/#limited-access-networks","title":"Limited access networks","text":"<p>If you are on a network that does not permit Internet access to the PowerShell Gallery, download the required PowerShell modules on an alternative device that has access. PowerShell provides the <code>Save-Module</code> cmdlet that can be run from a PowerShell terminal to do this.</p> <p>The following command lines can be used to download the required modules using a PowerShell terminal. After downloading the modules, copy the module directories to devices with restricted Internet access.</p> Runtime modulesDevelopment modules <p>To save PSRule for offline use:</p> <pre><code>Save-Module -Name 'PSRule' -Path '.\\modules'\n</code></pre> <p>This will save PSRule into the <code>modules</code> sub-directory.</p> <p>To save PSRule development module dependencies for offline use:</p> <pre><code>$modules = @('PlatyPS', 'Pester', 'PSScriptAnalyzer', 'PowerShellGet',\n'PackageManagement', 'InvokeBuild')\nSave-Module -Name $modules -Repository PSGallery -Path '.\\modules';\n</code></pre> <p>This will save required developments dependencies into the <code>modules</code> sub-directory.</p> <p>Tip</p> <p>If you use additional rules modules such as PSRule for Azure you should also save these for offline use.</p> <p>Note</p> <p>If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.</p>"},{"location":"license-contributing/","title":"License and contributing","text":"<p>PSRule is licensed with an  MIT License, which means it's free to use and modify. But please check out the details.</p> <p>We  open source at Microsoft.</p> <p>In addition to our team, we hope you will think about contributing too. Here is how you can get started:</p> <ul> <li> Report issues.</li> <li> Up-vote existing issues that are important to you.</li> <li> Improve documentation.</li> <li> <p> Contribute code.</p> </li> </ul>"},{"location":"related-projects/","title":"Related projects","text":"<p>The PSRule project is distributed across multiple repositories. You can find out more by visiting each repository.</p> Name Description ps-rule GitHub continuous integration using GitHub Actions. PSRule-pipelines Azure DevOps continuous integration using Azure Pipelines. PSRule-vscode Support for running and authoring rules within Visual Studio Code. PSRule.Monitor Support for logging PSRule analysis results to Azure Monitor. PSRule.Rules.Azure Rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Azure-quickstart Sample code you can use to quickly start using PSRule for Azure. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements."},{"location":"related-projects/#community-modules","title":"Community modules","text":"<p>The following third-party modules are created, maintained, supported, and licensed by their respective authors. Before consuming these module, double check they meet your organization's support, security, and licensing expectations.</p> Author Name Description cloudyspells PSRule.Rules.AzureDevOps A suite of rules to validate Azure DevOps projects using PSRule."},{"location":"support/","title":"Support","text":"<p>This project uses GitHub Issues to track bugs and feature requests.</p> <p>Please search the existing issues before filing new issues to avoid duplicates.</p> <ul> <li>For new issues, file your bug or feature request as a new issue.</li> <li>For help, discussion, and support questions about using this project, join or start a discussion.</li> </ul>"},{"location":"support/#microsoft-support-policy","title":"Microsoft Support Policy","text":"<p>Support for this project/ product is limited to the resources listed above.</p>"},{"location":"troubleshooting/","title":"Troubleshooting","text":"<p>Abstract</p> <p>This article provides troubleshooting instructions for common errors generic to PSRule or core functionality.</p> <p>Tip</p> <p>See troubleshooting specific to PSRule for Azure for common errors when testing Azure resources using the <code>PSRule.Rules.Azure</code> module.</p>"},{"location":"troubleshooting/#custom-rules-are-not-running","title":"Custom rules are not running","text":"<p>There is a few common causes of this issue including:</p> <ul> <li>Check rule path \u2014 By default, PSRule will look for rules in the <code>.ps-rule/</code> directory.   This directory is the root for your repository or the current working path by default.   On case-sensitive file systems such as Linux, this directory name is case-sensitive.   See Storing and naming rules for more information.</li> <li>Check file name suffix \u2014 PSRule only looks for files with the <code>.Rule.ps1</code>, <code>.Rule.yaml</code>, or <code>.Rule.jsonc</code> suffix.   On case-sensitive file systems such as Linux, this file suffix is case-sensitive.   See Storing and naming rules for more information.</li> <li>Check binding configuration \u2014 PSRule uses binding to work out which property to use for a resource type.   To be able to use the <code>-Type</code> parameter or <code>type</code> properties in rules definitions, binding must be set.   This is automatically configured for modules such as PSRule for Azure, however must be set in <code>ps-rule.yaml</code> for custom rules.</li> <li>Check modules \u2014 Check if your custom rules have a dependency on another module such as <code>PSRule.Rules.Azure</code>.   If your rules have a dependency, be sure to add the module in your command-line.</li> </ul> <p>Tip</p> <p>You may be able to use <code>git mv</code> to change the case of a file if it is committed to the repository incorrectly.</p>"},{"location":"troubleshooting/#windows-powershell-is-in-noninteractive-mode","title":"Windows PowerShell is in NonInteractive mode","text":"<p>When running PSRule on a Windows self-hosted agent/ private runner you may encounter an error similar to the following:</p> <p>Error</p> <p>Exception calling \"ShouldContinue\" with \"2\" argument(s): \"Windows PowerShell is in NonInteractive mode. Read and Prompt functionality is not available.\"</p> <p>This error may be caused by the PowerShell NuGet package provider not being installed. By default, Windows PowerShell does not have these components installed. These components are required for installing and checking versions of PSRule modules.</p> <p>To resolve this issue, install the NuGet package provider during setup the agent/ runner by using the following script:</p> <pre><code>if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction Ignore)) {\n    Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\n</code></pre> <p>Additionally consider installing the latest version of <code>PowerShellGet</code> by using the following script:</p> <pre><code>if ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion 2.2.1 -ErrorAction Ignore)) {\n    Install-Module PowerShellGet -MinimumVersion 2.2.1 -Scope CurrentUser -Force -AllowClobber;\n}\n</code></pre>"},{"location":"troubleshooting/#format-default-error-when-running-invoke-psrule","title":"Format-Default error when running Invoke-PSRule","text":"<p>When running PSRule you may encounter an error similar to the following:</p> <p>Error</p> <p>Format-Default: Cannot process argument because the value of argument \"name\" is not valid. Change the value of the \"name\" argument and run the operation again.</p> <p>This error is caused by a known issue in PowerShell 7.4.0 and 7.4.1. To resolve this issue, upgrade to PowerShell 7.4.2 or later.</p> <p>For more details see #1723.</p>"},{"location":"troubleshooting/#psr0001-unable-to-read-options-file","title":"PSR0001 - Unable to read options file","text":"<p>When running PSRule you may encounter an error similar to the following:</p> <p>Error</p> <p>PSR0001: Unable to read options file 'ps-rule.yaml'.</p> <p>This error typically indicates a problem with the YAML syntax in the <code>ps-rule.yaml</code> file. Double check the file for incorrect indentation or missing punctuation such as <code>-</code> and <code>:</code> characters.</p> <p>If you still have an issue, try re-saving the file as UTF-8 in an editor such as Visual Studio Code.</p>"},{"location":"troubleshooting/#psr0002-summary-results-are-not-supported-with-job-summaries","title":"PSR0002 - Summary results are not supported with Job Summaries","text":"<p>Error</p> <p>PSR0002: Summary results are not supported with Job Summaries.</p> <p>Currently using the <code>Output.As</code> with the <code>Summary</code> option is not supported with job summaries. Choose to use one or the other.</p> <p>If you have a specific use case your would like to enable, please start a discussion.</p>"},{"location":"troubleshooting/#psr0003-the-specified-baseline-group-is-not-known","title":"PSR0003 - The specified baseline group is not known","text":"<p>Error</p> <p>PSR0003: The specified baseline group 'latest' is not known.</p> <p>This error is caused by attempting to reference a baseline group which has not been defined. To define a baseline group, see Baseline.Group option.</p>"},{"location":"troubleshooting/#psr0004-the-specified-resource-is-not-known","title":"PSR0004 - The specified resource is not known","text":"<p>Error</p> <p>PSR0004: The specified Baseline resource 'TestModule4\\Module4' is not known.</p> <p>This error is caused when you attempt to reference a resource such as a baseline, rule, or selector which has not been defined.</p>"},{"location":"upgrade-notes/","title":"Upgrade notes","text":"<p>This document contains notes to help upgrade from previous versions of PSRule.</p>"},{"location":"upgrade-notes/#upgrading-to-v300","title":"Upgrading to v3.0.0","text":""},{"location":"upgrade-notes/#unbound-object-names","title":"Unbound object names","text":"<p>When an object is processed by PSRule, it is assigned a name. This name is used to identify the object in the output and to suppress the object from future processing.</p> <p>Prior to v3.0.0, the name was generated using a SHA-1 hash of the object. The SHA-1 algorithm is no longer considered secure and has been replaced with SHA-512.</p> <p>From v3.0.0, if the name of an object can not be determined, the SHA-512 hash of the object will be used. Any objects that have previously been suppressed with a name based on a SHA-1 hash will no longer be suppressed.</p> <p>To resolve any issue caused by this change, you can:</p> <ol> <li>Configure binding by setting the Binding.TargetName option to set an alternative property to use as the name. OR</li> <li> <p>Update any existing keys set with the Suppression option to use the new SHA-512 hash.</p> </li> </ol>"},{"location":"upgrade-notes/#using-powershell-74-or-later","title":"Using PowerShell 7.4 or later","text":"<p>From v3.0.0, PSRule requires:</p> <ul> <li>Windows PowerShell 5.1 for running as a PowerShell module. OR</li> <li>PowerShell 7.4 or later for development, building locally, or running as a PowerShell module.</li> </ul> <p>Support for Windows PowerShell 5.1 is deprecated and will be removed in a future release of PSRule (v4). We recommend upgrading to PowerShell 7.4 or later.</p>"},{"location":"upgrade-notes/#changes-to-cli-commands","title":"Changes to CLI commands","text":"<p>From v3.0.0, the CLI command names have been renamed to simplify usage. The following changes have been made:</p> <ul> <li>To run rules, use <code>run</code> instead of <code>analyze</code>. i.e. <code>ps-rule run</code>.</li> <li>To restore modules for a workspace, use <code>module restore</code> instead of <code>restore</code>. i.e. <code>ps-rule module restore</code>.</li> </ul> <p>The <code>run</code> command provides similar output to the <code>Assert-PSRule</code> cmdlet in PowerShell.</p> <p>Previously the <code>restore</code> command installed modules based on the configuration of the Requires option. From v3.0.0, the <code>module restore</code> command installs modules based on:</p> <ul> <li>The module lock file <code>ps-rule.lock.json</code> if set.   Use <code>module</code> CLI commands to manage the lock file. AND</li> <li> <p>Modules defined in the Include.Module option, if set.   Additionally the Requires option is used to constrain the version of modules installed.</p> </li> </ul>"},{"location":"upgrade-notes/#upgrading-to-v200","title":"Upgrading to v2.0.0","text":""},{"location":"upgrade-notes/#resources-naming-restrictions","title":"Resources naming restrictions","text":"<p>When naming resources such as rules or selectors, the following restrictions apply:</p> <ul> <li>Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.</li> <li>Only use allowed characters \u2014   To preserve consistency between file systems, some characters are not permitted.   Dots, hyphens, and underscores are not permitted at the start and end of the name.   Additionally some characters are restricted for future use.   The following characters are not permitted:<ul> <li><code>&lt;</code> (less than)</li> <li><code>&gt;</code> (greater than)</li> <li><code>:</code> (colon)</li> <li><code>/</code> (forward slash)</li> <li><code>\\</code> (backslash)</li> <li><code>|</code> (vertical bar or pipe)</li> <li><code>?</code> (question mark)</li> <li><code>*</code> (asterisk)</li> <li><code>\"</code> (double quote)</li> <li><code>'</code> (single quote)</li> <li><code>`</code> (backtick)</li> <li><code>+</code> (plus)</li> <li><code>@</code> (at sign)</li> <li>Integer value zero, sometimes referred to as the ASCII NUL character.</li> <li>Characters whose integer representations are in the range from 1 through 31.</li> </ul> </li> </ul> <p>Prior to v2.0.0, there was no specific naming restriction for resources. However functionally PSRule and downstream components could not support all resource names. To avoid confusion, we have decided to restrict resource names to a specific set of characters.</p> <p>From v2.0.0, resource names that do not meet the naming restrictions will generate an error.</p> Regular expression for valid resource names<pre><code>^[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^&lt;&gt;:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\n</code></pre>"},{"location":"upgrade-notes/#setting-default-module-baseline","title":"Setting default module baseline","text":"<p>When packaging rules in a module, you can set the default baseline. The default baseline from the module will be automatically used unless overridden.</p> <p>Prior to v1.9.0 the default baseline was set by configuring the module manifest <code>.psd1</code> file. From v1.9.0 the default baseline can be configured by within a module configuration. Using module configuration is the recommended method. Setting the default baseline from module manifest and has been removed from v2.0.0.</p> <p>A module configuration can be defined in YAML.</p> <p>Example</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  rule:\n    baseline: Enterprise.Default\n</code></pre>"},{"location":"upgrade-notes/#setting-resource-api-version","title":"Setting resource API version","text":"<p>When creating YAML and JSON resources you define a resource by specifying the <code>apiVersion</code> and <code>kind</code>. An <code>apiVersion</code> was added as a requirement from v1.2.0. For compatibility, resources without an <code>apiVersion</code> were supported however deprecated for removal. This has now been removed from v2.0.0.</p> <p>When defining resource specify an <code>apiVersion</code>. Currently this must be set to <code>github.com/microsoft/PSRule/v1</code>.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre>"},{"location":"upgrade-notes/#change-in-source-file-discovery-for-get-psrulehelp","title":"Change in source file discovery for Get-PSRuleHelp","text":"<p>Previously in PSRule v1.11.0 and prior versions, rules would show up twice when running <code>Get-PSRuleHelp</code> in the context of a module and in the same working directory of the module. This behavior has now been removed from v2.0.0.</p> <p>Module files are now preferred over loose files, and rules are only shown once in the output. Any duplicate rule names from loose files are outputted as a warning instead.</p> <p>The old behavior:</p> <pre><code>Name                                ModuleName               Synopsis\n----                                ----------               --------\nM1.Rule1                                                     This is the default\nM1.Rule2                                                     This is the default\nM1.Rule1                            TestModule               Synopsis en-AU.\nM1.Rule2                            TestModule               This is the default\n</code></pre> <p>The new behavior:</p> <pre><code>WARNING: A rule with the same name 'M1.Rule1' already exists.\nWARNING: A rule with the same name 'M1.Rule2' already exists.\n\nName                                ModuleName               Synopsis\n----                                ----------               --------\nM1.Rule1                            TestModule               Synopsis en-AU.\nM1.Rule2                            TestModule               This is the default\n</code></pre>"},{"location":"upgrade-notes/#require-source-discovery-from-current-working-directory-to-be-explicitly-included","title":"Require source discovery from current working directory to be explicitly included","text":"<p>Previously in PSRule v1.11.0 and prior versions, rule sources from the current working directory without the <code>-Path</code> and <code>-Module</code> parameters were automatically included. This behavior has now been removed from v2.0.0.</p> <p>Rules sources in the current working directory are only included if <code>-Path .</code> or <code>-Path $PWD</code> is specified.</p> <p>The old behavior:</p> PowerShell<pre><code>Set-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\nRuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nappServicePlan.MinInstanceCount                                App Service Plan has multiple instances\nappServicePlan.MinPlan                                         Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity                                      Disable client affinity for stateless services\nappServiceApp.UseHTTPS                                         Use HTTPS only\nstorageAccounts.UseHttps                                       Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption                                  Use at-rest storage encryption\n</code></pre> <p>The new behavior:</p> PowerShell<pre><code>Set-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\n# No output, need to specify -Path explicitly\n\nGet-PSRule -Path $PWD\n\nRuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nappServicePlan.MinInstanceCount                                App Service Plan has multiple instances\nappServicePlan.MinPlan                                         Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity                                      Disable client affinity for stateless services\nappServiceApp.UseHTTPS                                         Use HTTPS only\nstorageAccounts.UseHttps                                       Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption      \n</code></pre>"},{"location":"upgrade-notes/#upgrading-to-v140","title":"Upgrading to v1.4.0","text":"<p>Follow these notes to upgrade to PSRule v1.4.0 from previous versions.</p>"},{"location":"upgrade-notes/#change-in-default-output-styles","title":"Change in default output styles","text":"<p>Previously in PSRule v1.3.0 and prior the default style when using <code>Assert-PSRule</code> was <code>Client</code>. From v1.4.0 PSRule now defaults to <code>Detect</code>.</p> <p>The <code>Detect</code> output style falls back to <code>Client</code> however may detect one of the following styles instead:</p> <ul> <li><code>AzurePipelines</code> - Output is written for integration Azure Pipelines.</li> <li><code>GitHubActions</code> - Output is written for integration GitHub Actions.</li> <li><code>VisualStudioCode</code> - Output is written for integration with Visual Studio Code.</li> </ul> <p>Detect uses the following logic:</p> <ol> <li>If the <code>TF_BUILD</code> environment variable is set to <code>true</code>, <code>AzurePipelines</code> will be used.</li> <li>If the <code>GITHUB_ACTIONS</code> environment variable is set to <code>true</code>, <code>GitHubActions</code> will be used.</li> <li>If the <code>TERM_PROGRAM</code> environment variable is set to <code>vscode</code>, <code>VisualStudioCode</code> will be used.</li> <li>Use <code>Client</code>.</li> </ol> <p>To force usage of the <code>Client</code> output style set the <code>Output.Style</code> option. For example:</p> ps-rule.yaml<pre><code># YAML: Using the output/style property\noutput:\n  style: Client\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=Client\n</code></pre> GitHub Actions<pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_STYLE: Client\n</code></pre> Azure Pipelines<pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n  value: Client\n</code></pre>"},{"location":"upgrade-notes/#upgrading-to-v100","title":"Upgrading to v1.0.0","text":"<p>Follow these notes to upgrade to PSRule v1.0.0 from previous versions.</p>"},{"location":"upgrade-notes/#replaced-rule-target-properties","title":"Replaced $Rule target properties","text":"<p>Previously in PSRule v0.22.0 and prior the <code>$Rule</code> automatic variable had the following properties:</p> <ul> <li><code>TargetName</code></li> <li><code>TargetType</code></li> <li><code>TargetObject</code></li> </ul> <p>For example:</p> PowerShell rules<pre><code>Rule 'Rule1' {\n    $Rule.TargetName -eq 'Name1';\n    $Rule.TargetType -eq '.json';\n    $Rule.TargetObject.someProperty -eq 1;\n}\n</code></pre> <p>In v1.0.0 these properties have been removed after being deprecated in v0.12.0. These properties are instead available on the <code>$PSRule</code> variable. Rules referencing the deprecated properties of <code>$Rule</code> must be updated.</p> <p>For example:</p> PowerShell rules<pre><code>Rule 'Rule1' {\n    $PSRule.TargetName -eq 'Name1';\n    $PSRule.TargetType -eq '.json';\n    $PSRule.TargetObject.someProperty -eq 1;\n}\n</code></pre>"},{"location":"validating-locally/","title":"Validating locally","text":"<p>PSRule can be installed locally on MacOS, Linux, and Windows for local validation. This allows you to test Infrastructure as Code (IaC) artifacts before pushing changes to a repository.</p> <p>Tip</p> <p>If you haven't already, follow the instructions on installing locally before continuing.</p>"},{"location":"validating-locally/#with-visual-studio-code","title":"With Visual Studio Code","text":"<p> Extension</p> <p>An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in task PSRule: Run analysis task.</p> <p> </p> <p>Info</p> <p>To learn about tasks in Visual Studio Code see Integrate with External Tools via Tasks.</p>"},{"location":"validating-locally/#customizing-the-task","title":"Customizing the task","text":"<p>The PSRule: Run analysis task will be available automatically after you install the PSRule extension. You can customize the defaults of the task by editing or inserting the task into <code>.vscode/tasks.json</code> within your workspace.</p> JSON<pre><code>{\n    \"type\": \"PSRule\",\n    \"problemMatcher\": [\n        \"$PSRule\"\n    ],\n    \"label\": \"PSRule: Run analysis\",\n    \"modules\": [\n        \"PSRule.Rules.Azure\"\n    ],\n    \"presentation\": {\n        \"clear\": true,\n        \"panel\": \"dedicated\"\n    }\n}\n</code></pre> <p>Example</p> <p>A complete <code>.vscode/tasks.json</code> might look like the following:</p> .vscode/tasks.json<pre><code>{\n    \"version\": \"2.0.0\",\n    \"tasks\": [\n        {\n            \"type\": \"PSRule\",\n            \"problemMatcher\": [\n                \"$PSRule\"\n            ],\n            \"label\": \"PSRule: Run analysis\",\n            \"modules\": [\n                \"PSRule.Rules.Azure\"\n            ],\n            \"presentation\": {\n                \"clear\": true,\n                \"panel\": \"dedicated\"\n            }\n        }\n    ]\n}\n</code></pre>"},{"location":"versioning/","title":"Changes and versioning","text":"<p>PSRule uses semantic versioning to declare breaking changes. The latest module version can be installed from the PowerShell Gallery. For a list of module changes please see the change log.</p>"},{"location":"versioning/#pre-releases","title":"Pre-releases","text":"<p>Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Module versions and change log details for pre-releases will be removed as stable releases are made available.</p> <p>Important</p> <p>Pre-release versions should be considered work in progress. These releases should not be used in production. We may introduce breaking changes between a pre-release as we work towards a stable version release.</p>"},{"location":"versioning/#experimental-features","title":"Experimental features","text":"<p>From time to time we may ship experiential features. These features are generally marked experiential in the change log as these features ship. Experimental features may ship in stable releases, however to use them you may need to:</p> <ul> <li>Enable or explicitly reference them.</li> </ul> <p>Important</p> <p>Experimental features should be considered work in progress. These features may be incomplete and should not be used in production. We may introduce breaking changes for experimental features as we work towards a general release for the feature.</p>"},{"location":"versioning/#reporting-bugs","title":"Reporting bugs","text":"<p>If you experience an issue with an pre-release or experimental feature please let us know by logging an issue as a bug.</p>"},{"location":"authoring/packaging-rules/","title":"Packaging rules in a module","text":"<p>PSRule supports distribution of rules within modules. Using a module, rules can be published and installed using standard PowerShell cmdlets.</p> <p>You should consider packaging rules into a module to:</p> <ul> <li>Version rules. PowerShell modules support semantic versioning (semver).</li> <li>Reuse rules across projects, pipelines or teams.</li> <li>Publish rules to external consumers via the PowerShell Gallery.</li> </ul> <p>This scenario covers the following:</p> <ul> <li>Creating a module manifest</li> <li>Including rules and baselines</li> <li>Defining a module configuration</li> <li>Including documentation</li> </ul>"},{"location":"authoring/packaging-rules/#creating-a-module-manifest","title":"Creating a module manifest","text":"<p>When creating a PowerShell module, a module manifest is an optional file that stores module metadata. Module manifests use the <code>.psd1</code> file extension. When packaging rules in a module, a module manifest is required for PSRule discover the module.</p>"},{"location":"authoring/packaging-rules/#creating-the-manifest-file","title":"Creating the manifest file","text":"<p>A module manifest can be created from PowerShell using the <code>New-ModuleManifest</code> cmdlet. Additionally, Visual Studio Code and many other tools also include snippets for creating a module manifest.</p> <p>For example:</p> <pre><code># Create a directory for the module\nmd ./Enterprise.Rules;\n\n# Create the manifest\nNew-ModuleManifest -Path ./Enterprise.Rules/Enterprise.Rules.psd1 -Tags 'PSRule-rules';\n</code></pre> <p>The example above creates a module manifest for a module named Enterprise.Rules tagged with <code>PSRule-rules</code>. The use of the <code>PSRule-rules</code> tag is explained in the following section.</p>"},{"location":"authoring/packaging-rules/#setting-module-tags","title":"Setting module tags","text":"<p>When PSRule cmdlets are used with the <code>-Module</code> parameter, PSRule discovers rule modules. If the module is already imported, that module is used. If the module is not imported, PSRule will import the highest version of the module automatically.</p> <p>For a module to be discovered by PSRule, tag the module with <code>PSRule-rules</code>. To tag modules, find the <code>Tags</code> section the <code>PSData</code> hashtable in the module manifest and add <code>PSRule-rules</code>.</p> <p>An updated module manifest may look like this:</p> <pre><code># Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.\nPrivateData = @{\n    PSData = @{\n        # Tags applied to this module. These help with module discovery in online galleries.\n        Tags = @('PSRule-rules')\n    }\n}\n</code></pre>"},{"location":"authoring/packaging-rules/#including-rules-and-baselines","title":"Including rules and baselines","text":"<p>Rules and baselines can be included anywhere within the module directory structure. Such as in the root directory of the module or in a nested sub-directory.</p> <p>By convention, consider including rules and baselines within a <code>rules</code> sub-directory within the module.</p> <p>For example:</p> <ul> <li>Enterprise.Rules/<ul> <li>rules/<ul> <li>Baseline.Rule.yaml</li> <li>Config.Rule.yaml</li> <li>Standards.Rule.ps1</li> </ul> </li> <li>Enterprise.Rules.psd1</li> </ul> </li> </ul>"},{"location":"authoring/packaging-rules/#file-names","title":"File names","text":"<p>For PSRule to find rules included in a module, rule file names must end with the <code>.Rule.ps1</code> suffix. We recommend using the exact case <code>.Rule.ps1</code>. This is because some file systems are case-sensitive. For example, on Linux <code>Standards.rule.ps1</code> would be ignored by PSRule.</p> <p>Similarly, when including baselines within a module use the <code>.Rule.yaml</code> suffix.</p>"},{"location":"authoring/packaging-rules/#defining-a-module-configuration","title":"Defining a module configuration","text":"<p>A module configuration that sets options defaults and can be optionally packaged with a module. To set a module configuration, define a <code>ModuleConfig</code> resource within an included <code>.Rule.yaml</code> file. A module configuration <code>.Rule.yaml</code> file must be distributed within the module directory structure.</p> <p>PSRule only supports a single <code>ModuleConfig</code> resource. The name of the <code>ModuleConfig</code> must match the name of the module. Additional <code>ModuleConfig</code> resources or with an alternative name are ignored. PSRule does not support module configurations distributed outside of a module.</p> <p>Example</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  binding:\n    targetName:\n    - ResourceName\n    - FullName\n    - name\n    targetType:\n    - ResourceType\n    - type\n    - Extension\n    field:\n      resourceId: [ 'ResourceId' ]\n      subscriptionId: [ 'SubscriptionId' ]\n      resourceGroupName: [ 'ResourceGroupName' ]\n  rule:\n    baseline: Enterprise.Default\n</code></pre> <p>The following options are allowed within a <code>ModuleConfig</code>:</p> <ul> <li><code>Binding.Field</code></li> <li><code>Binding.IgnoreCase</code></li> <li><code>Binding.NameSeparator</code></li> <li><code>Binding.PreferTargetInfo</code></li> <li><code>Binding.TargetName</code></li> <li><code>Binding.TargetType</code></li> <li><code>Binding.UseQualifiedName</code></li> <li><code>Configuration</code></li> <li><code>Output.Culture</code></li> <li><code>Rule.Baseline</code></li> </ul>"},{"location":"authoring/packaging-rules/#setting-a-default-baseline","title":"Setting a default baseline","text":"<p>Optionally, baselines can be included in rule modules. If a baseline contains configuration or binding options then setting a default baseline is often desirable. When a default baseline is set, PSRule will use the named baseline automatically when processing rules from that module. This feature removes the need for users to specify it manually.</p> <p>To set a default baseline, set the <code>Rule.Baseline</code> property of the <code>ModuleConfig</code> resource.</p> <p>Example</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  binding:\n    targetName:\n    - ResourceName\n    - FullName\n    - name\n    targetType:\n    - ResourceType\n    - type\n    - Extension\n    field:\n      resourceId: [ 'ResourceId' ]\n      subscriptionId: [ 'SubscriptionId' ]\n      resourceGroupName: [ 'ResourceGroupName' ]\n  rule:\n    baseline: Enterprise.Default\n</code></pre> <p>This examples set the default baseline to <code>Enterprise.Default</code>. The default baseline must be included in file ending with <code>.Rule.yaml</code> within the module directory structure.</p>"},{"location":"authoring/packaging-rules/#including-documentation","title":"Including documentation","text":"<p>PSRule supports write and packaging rule modules with markdown documentation. Markdown documentation is automatically interpreted by PSRule and included in output.</p> <p>When including markdown, files are copied into a directory structure based on the target culture.</p> <p>For example, store documentation targeted to the culture <code>en-US</code> in a directory named <code>en-US</code>. Similarly, documentation for cultures such as <code>en-AU</code>, <code>en-GB</code> and <code>fr-FR</code> would be in separate directories.</p> <p>If a directory for the exact culture <code>en-US</code> doesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory named <code>en</code>.</p> <p>When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux <code>en-us</code> would not match.</p> <p>For example:</p> <ul> <li>Enterprise.Rules/<ul> <li>en/<ul> <li>Org.Az.Storage.UseHttps.md</li> <li>Org.Az.Resource.Tagging.md</li> </ul> </li> <li>en-US/<ul> <li>Org.Az.Storage.UseHttps.md</li> </ul> </li> <li>fr-FR/<ul> <li>Org.Az.Storage.UseHttps.md</li> </ul> </li> <li>rules/<ul> <li>Baseline.Rule.yaml</li> <li>Config.Rule.yaml</li> <li>Standards.Rule.ps1</li> </ul> </li> <li>Enterprise.Rules.psd1</li> </ul> </li> </ul>"},{"location":"authoring/packaging-rules/#more-information","title":"More information","text":"<ul> <li>Enterprise.Rules.psd1 - An example module manifest.</li> <li>Baseline.Rule.yaml - An example baseline.</li> <li>Config.Rule.yaml - An example module configuration.</li> </ul>"},{"location":"authoring/storing-rules/","title":"Storing and naming rules","text":"<p>Rules are stored in one or more files and each file can contain one or many rules. Additionally, rules can be grouped into a module and distributed.</p> <p>Abstract</p> <p>This topic covers recommendations for naming and storing rules.</p>"},{"location":"authoring/storing-rules/#using-a-standard-file-path","title":"Using a standard file path","text":"<p>Rules can be standalone or packaged within a module. Standalone rules are ideal for a single project such as an Infrastructure as Code (IaC) repository. To reuse rules across multiple projects consider packaging these as a module.</p> <p>The instructions for packaging rules in a module can be found here:</p> <ul> <li>Packaging rules in a module</li> </ul> <p>To store standalone rules we recommend that you:</p> <ul> <li>Use .ps-rule/ \u2014 Create a sub-directory called <code>.ps-rule</code> in the root of your repository.   Use all lower-case in the sub-directory name.   Put any custom rules within this sub-directory.</li> <li>Use files ending with .Rule.* \u2014 PSRule uses a file naming convention to discover rules.   Use one of the following depending on the file format you are using:<ul> <li>YAML - <code>.Rule.yaml</code>.</li> <li>JSON - <code>.Rule.jsonc</code> or <code>.Rule.json</code>.</li> <li>PowerShell - <code>.Rule.ps1</code>.</li> </ul> </li> </ul> <p>Note</p> <p>Build pipelines are often case-sensitive or run on Linux-based systems. Using the casing rule above reduces confusion latter when you configure continuous integration (CI).</p>"},{"location":"authoring/storing-rules/#naming-rules","title":"Naming rules","text":"<p>When running PSRule, rule names must be unique. For example, PSRule for Azure uses the name prefix of <code>Azure.</code> for rules included in the module.</p> <p>Example</p> <p>The following names are examples of rules included within PSRule for Azure:</p> <ul> <li><code>Azure.AKS.Version</code></li> <li><code>Azure.AKS.AuthorizedIPs</code></li> <li><code>Azure.SQL.MinTLS</code></li> </ul> <p>In addition, names for rules and other resources must meet the following requirements:</p> <ul> <li>Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.</li> <li>Only use allowed characters \u2014   To preserve consistency between file systems, some characters are not permitted.   Dots, hyphens, and underscores are not permitted at the start and end of the name.   Additionally some characters are restricted for future use.   The following characters are not permitted:<ul> <li><code>&lt;</code> (less than)</li> <li><code>&gt;</code> (greater than)</li> <li><code>:</code> (colon)</li> <li><code>/</code> (forward slash)</li> <li><code>\\</code> (backslash)</li> <li><code>|</code> (vertical bar or pipe)</li> <li><code>?</code> (question mark)</li> <li><code>*</code> (asterisk)</li> <li><code>\"</code> (double quote)</li> <li><code>'</code> (single quote)</li> <li><code>`</code> (backtick)</li> <li><code>+</code> (plus)</li> <li><code>@</code> (at sign)</li> <li>Integer value zero, sometimes referred to as the ASCII NUL character.</li> <li>Characters whose integer representations are in the range from 1 through 31.</li> </ul> </li> </ul> Regular expression for valid resource names<pre><code>^[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^&lt;&gt;:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^&lt;&gt;:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\n</code></pre> <p>When naming rules we recommend that you:</p> <ul> <li>Use a standard prefix \u2014 You can use the <code>Local.</code> or <code>Org.</code> prefix for standalone rules.<ul> <li>Alternatively choose a short prefix that identifies your organization.</li> </ul> </li> <li>Use dotted notation \u2014 Use dots to separate rule name.</li> <li>Use a maximum length of 35 characters \u2014   The default view of <code>Invoke-PSRule</code> truncates longer names.   PSRule supports longer rule names however if <code>Invoke-PSRule</code> is called directly consider using <code>Format-List</code>.</li> <li> <p>Avoid using special characters and punctuation \u2014   Although these characters can be used in many cases, they may not be easy to use with all PSRule features.</p> </li> </ul>"},{"location":"authoring/testing-infrastructure/","title":"Testing infrastructure","text":"<p>You can use PSRule to create tests for Infrastructure as Code (IaC). Each test is called a rule.</p> <p>PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.</p> <p>Abstract</p> <p>This topic covers how to create a rule using YAML, JSON, and PowerShell by example. This example, while fictitious is indicative of common testing and validation scenarios for IaC.</p>"},{"location":"authoring/testing-infrastructure/#sample-data","title":"Sample data","text":"<p>To get started authoring a rule, we will be working with a sample file <code>settings.json</code>. This sample configuration file configures an application.</p> <p>For the purpose of this example, one configuration setting <code>supportsHttpsTrafficOnly</code> is set. This configuration setting can be either <code>true</code> or <code>false</code>. When set to <code>true</code>, Transport Layer Security (TLS) is enforced. When set to <code>false</code>, the application permits insecure communication with HTTP.</p> <p>Contents of <code>settings.json</code></p> <p>Create a <code>settings.json</code> file in the root of your repository with the following contents.</p> <pre><code>{\n    \"type\": \"app1\",\n    \"version\": 1,\n    \"configure\": {\n        \"supportsHttpsTrafficOnly\": false\n    }\n}\n</code></pre>"},{"location":"authoring/testing-infrastructure/#define-a-rule","title":"Define a rule","text":"<p>To meet the requirements of our organization we want to write a rule to:</p> <ul> <li>Enforce secure traffic by requiring <code>supportsHttpsTrafficOnly</code> to be <code>true</code>.</li> <li>Enforce use of TLS 1.2 as a minimum by requiring <code>minTLSVersion</code> to be <code>1.2</code>.</li> </ul> <p>In this section the same rule will be authored using YAML, JSON, and PowerShell.</p> <p>Tip</p> <p>To make you editing experience even better, consider installing the Visual Studio Code extension.</p> YAMLJSONPowerShell <p>Create a <code>.ps-rule/Local.Rule.yaml</code> file in your repository with the following contents.</p> <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test <code>settings.json</code>.     Specifically, the object path <code>configures.supportsHttpsTrafficOnly</code> must exist and be set to <code>true</code>.</li> </ol> <p>Create a <code>.ps-rule/Local.Rule.jsonc</code> file in your repository with the following contents.</p> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test <code>settings.json</code>.     Specifically, the object path <code>configures.supportsHttpsTrafficOnly</code> must exist and be set to <code>true</code>.</li> </ol> <p>Create a <code>.ps-rule/Local.Rule.ps1</code> file in your repository with the following contents.</p> <pre><code># Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n    $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n}\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name.</li> <li>The condition contained within the curly braces <code>{ }</code> determines the checks PSRule will use to test <code>settings.json</code>.</li> <li>The <code>$Assert.HasFieldValue</code> method checks the object path <code>configures.supportsHttpsTrafficOnly</code> exists and is set to <code>true</code>.</li> </ol> <p>Tip</p> <p>To learn more about recommended file and naming conventions for rules, continue reading Storing and naming rules.</p>"},{"location":"authoring/testing-infrastructure/#using-multiple-conditions","title":"Using multiple conditions","text":"<p>Each rule must have at least one condition. Additional conditions can be combined to check multiple test cases.</p> <p>In the example a <code>minTLSVersion</code> configuration setting does not exist and is not set.</p> YAMLJSONPowerShell <p>Update <code>.ps-rule/Local.Rule.yaml</code> in your repository with the following contents.</p> <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    allOf:\n    - field: 'configure.supportsHttpsTrafficOnly'\n      equals: true\n    - field: 'configure.minTLSVersion'\n      equals: '1.2'\n</code></pre> <ol> <li>Using the <code>allOf</code> expression requires that all conditions be true for the rule to pass.     This expression allows an array of one or more conditions to be provided.     Using <code>anyOf</code> would pass the rule if any single condition is true.</li> </ol> <p>Update <code>.ps-rule/Local.Rule.jsonc</code> in your repository with the following contents.</p> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"allOf\": [\n                    {\n                        \"field\": \"configure.supportsHttpsTrafficOnly\",\n                        \"equals\": true\n                    },\n                    {\n                        \"field\": \"configure.minTLSVersion\",\n                        \"equals\": \"1.2\"\n                    }\n                ]\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Using the <code>allOf</code> expression requires that all conditions be true for the rule to pass.     This expression allows an array of one or more conditions to be provided.     Using <code>anyOf</code> would pass the rule if any single condition is true.</li> </ol> <p>Update <code>.ps-rule/Local.Rule.ps1</code> in your repository with the following contents.</p> <pre><code># Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n    $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n    $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\n</code></pre> <ol> <li>An additional, <code>$Assert.HasFieldValue</code> assertion helper method can be called.     The rule will pass if all of the conditions return true.</li> </ol>"},{"location":"authoring/testing-infrastructure/#testing","title":"Testing","text":""},{"location":"authoring/testing-infrastructure/#testing-manually","title":"Testing manually","text":"<p>To test the rule manually, run the following command.</p> <pre><code>Assert-PSRule -f ./settings.json\n</code></pre>"},{"location":"authoring/testing-infrastructure/#advanced-usage","title":"Advanced usage","text":""},{"location":"authoring/testing-infrastructure/#severity-level","title":"Severity level","text":"<p> v2.0.0</p> <p>When defining a rule, you can specify a severity level. The severity level is used if the rule fails. By default, the severity level for a rule is <code>Error</code>.</p> <ul> <li><code>Error</code> - A serious problem that must be addressed before going forward.</li> <li><code>Warning</code> - A problem that should be addressed.</li> <li><code>Information</code> - A minor problem or an opportunity to improve the code.</li> </ul> <p>In a continuous integration (CI) pipeline, severity level is particularly important. If any rule fails with a severity level of <code>Error</code> the pipeline will fail. This helps prevent serious problems from being introduced into the code base or deployed.</p> <p>The following example shows how to set the severity level to <code>Warning</code>.</p> YAMLJSONPowerShell <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  level: Warning\n  condition:\n    allOf:\n    - field: 'configure.supportsHttpsTrafficOnly'\n      equals: true\n    - field: 'configure.minTLSVersion'\n      equals: '1.2'\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"level\": \"Warning\",\n            \"condition\": {\n                \"allOf\": [\n                    {\n                        \"field\": \"configure.supportsHttpsTrafficOnly\",\n                        \"equals\": true\n                    },\n                    {\n                        \"field\": \"configure.minTLSVersion\",\n                        \"equals\": \"1.2\"\n                    }\n                ]\n            }\n        }\n    }\n]\n</code></pre> <p>Update <code>.ps-rule/Local.Rule.ps1</code> in your repository with the following contents.</p> <pre><code># Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' -Level Warning {\n    $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n    $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\n</code></pre>"},{"location":"authoring/using-expressions/","title":"Using expressions","text":"<p>PSRule allows you to write rules using YAML, JSON, or PowerShell. This offers a lot of flexibility to use PSRule for a variety of use cases. Some examples of use cases for each format include:</p> <ul> <li>YAML \u2014 Start authoring quickly with minimal knowledge of PowerShell.</li> <li>JSON \u2014 Generate rules automatically using automation tools.</li> <li>PowerShell \u2014 Integrate with other tools using PowerShell cmdlets.</li> </ul> <p>Abstract</p> <p>This topic covers the differences and limitations between authoring rules using YAML, JSON, and PowerShell. For an example of authoring rules see Writing rules or Testing infrastructure topics.</p>"},{"location":"authoring/using-expressions/#language-comparison","title":"Language comparison","text":"<p>Expressions and assertion methods can be used to build similar conditions.</p> <ul> <li>Expressions \u2014 Schema-based conditions written in YAML or JSON.   Expressions can be used in rules and selectors.</li> <li>Assertion methods \u2014 PowerShell-based condition helpers that make rules faster to author.   Assertion methods can be used in combination with standard PowerShell code to build rules or conventions.</li> </ul>"},{"location":"authoring/using-expressions/#quick-reference","title":"Quick reference","text":"<p>In most cases expressions and assertion method names match. There are some cases where these names do not directly align. This lookup table provides a quick reference for expressions and their assertion method counterpart.</p> Expression Assertion method Contains Contains Count Count Equals <sup>1</sup> n/a EndsWith EndsWith Exists HasField Greater Greater GreaterOrEquals GreaterOrEqual HasDefault HasDefaultValue HasSchema HasJsonSchema HasValue <sup>1</sup> n/a In In IsLower IsLower IsString IsString IsUpper IsUpper Less Less LessOrEquals LessOrEqual Match Match NotEquals n/a NotIn NotIn NotMatch NotMatch SetOf SetOf StartsWith StartsWith Subset Subset Version Version n/a FileHeader n/a FilePath n/a HasFields n/a HasFieldValue <sup>1</sup> IsArray IsArray IsBoolean IsBoolean IsDateTime IsDateTime IsInteger IsInteger IsNumeric IsNumeric n/a JsonSchema Exists NotHasField n/a NotNull NotWithinPath NotWithinPath n/a Null n/a NullOrEmpty n/a TypeOf WithinPath WithinPath <ol> <li> <p>The <code>Equals</code>, <code>HasValue</code> expressions and <code>HasFieldValue</code> are similar.\u00a0\u21a9\u21a9\u21a9</p> </li> </ol>"},{"location":"authoring/writing-rule-help/","title":"Writing rule help","text":"<p>PSRule has built-in support for help. Documentation can optionally be added for each rule to provide detailed information or remediation steps.</p> <p>This scenario covers the following:</p> <ul> <li>Using inline help</li> <li>Writing markdown documentation</li> <li>Localizing documentation files</li> </ul>"},{"location":"authoring/writing-rule-help/#inline-help-with-yaml-and-json","title":"Inline help with YAML and JSON","text":"<p>With authoring rules in YAML and JSON, PSRule provides the following syntax features:</p> <ul> <li>Synopsis resource comment.</li> <li><code>metadata.displayName</code> property.</li> <li><code>metadata.description</code> property.</li> <li><code>metadata.link</code> property.</li> <li><code>spec.recommend</code> property.</li> </ul>"},{"location":"authoring/writing-rule-help/#synopsis-resource-comment","title":"Synopsis resource comment","text":"<p>Specify the synopsis of the rule with the <code>Synopsis</code> comment above the rule properties.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>The resource comment is not localized. Use markdown documentation for a localized synopsis.</p>"},{"location":"authoring/writing-rule-help/#display-name-property","title":"Display name property","text":"<p>Specify the display name of the rule with the <code>metadata.displayName</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\n  displayName: Require TLS\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\",\n            \"displayName\": \"Require TLS\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized display name.</p>"},{"location":"authoring/writing-rule-help/#description-property","title":"Description property","text":"<p>Specify the description of the rule with the <code>metadata.description</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\n  description: The resource should only use TLS.\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\",\n            \"description\": \"The resource should only use TLS.\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized description.</p>"},{"location":"authoring/writing-rule-help/#link-property","title":"Link property","text":"<p>Specify the online help URL of the rule with the <code>metadata.link</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\n  link: https://aka.ms/ps-rule\nspec:\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\",\n            \"link\": \"https://aka.ms/ps-rule\"\n        },\n        \"spec\": {\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized online help URL.</p>"},{"location":"authoring/writing-rule-help/#recommend-property","title":"Recommend property","text":"<p>Specify the rule recommendation with the <code>spec.recommend</code> property.</p> YAMLJSON <pre><code>---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Local.YAML.RequireTLS'\nspec:\n  recommend: The resource should only use TLS.\n  condition:\n    field: 'configure.supportsHttpsTrafficOnly'\n    equals: true\n</code></pre> <pre><code>[\n    {\n        // Synopsis: An example rule to require TLS.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Local.JSON.RequireTLS\"\n        },\n        \"spec\": {\n            \"recommend\": \"\",\n            \"condition\": {\n                \"field\": \"configure.supportsHttpsTrafficOnly\",\n                \"equals\": true\n            }\n        }\n    }\n]\n</code></pre> <p>Note</p> <p>This property is not localized. Use markdown documentation for a localized recommendation.</p>"},{"location":"authoring/writing-rule-help/#inline-help-with-powershell","title":"Inline help with PowerShell","text":"<p>When authoring rules in PowerShell, PSRule provides the following syntax features:</p> <ul> <li>Synopsis script comment.</li> <li><code>Recommend</code> keyword.</li> <li><code>Reason</code> keyword.</li> </ul> <p>These features are each describe in detail in the following sections.</p>"},{"location":"authoring/writing-rule-help/#synopsis-script-comment","title":"Synopsis script comment","text":"<p>Comment metadata can be included directly above a rule block by using the syntax <code># Synopsis: &lt;text&gt;</code>. This is only supported for populating a rule synopsis.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>This example above would set the synopsis to <code>Must have the app.kubernetes.io/name label</code>.</p> <p>Including comment metadata improves authoring by indicating the rules purpose. Only a single line is supported. A rule synopsis is displayed when using <code>Get-PSRule</code> and <code>Get-PSRuleHelp</code>. The synopsis can not break over multiple lines.</p> <p>The key limitation of only using comment metadata is that it can not be localized for multiple languages. Consider using comment metadata and also using markdown documentation for a multi-language experience.</p> <p>Note</p> <p>The script comment is not localized. Use markdown documentation for a localized synopsis.</p>"},{"location":"authoring/writing-rule-help/#recommend-keyword","title":"Recommend keyword","text":"<p>The <code>Recommend</code> keyword sets the recommendation for a rule. Use the keyword with a text recommendation at the top of your rule body.</p> <p>Using the <code>Recommend</code> keyword is recommended for rules that are not packaged in a module. When packaging rules in a module consider using markdown help instead.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend 'Consider setting the recommended label ''app.kubernetes.io/name'' on deployment and service resources.'\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>A rule recommendation is displayed when using <code>Invoke-PSRule</code> or <code>Get-PSRuleHelp</code>.</p> <p>Only use the <code>Recommend</code> keyword once to set the recommendation text and avoid formatting with variables. Recommendations are cached the first time they are used. Supplying a unique recommendation within a rule based on conditions/ logic is not supported. To return a custom unique reason for why the rule failed, use the <code>Reason</code> keyword.</p> <p>Localized recommendations can set by using the <code>$LocalizedData</code>.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend $LocalizedData.RecommendNameLabel\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre>"},{"location":"authoring/writing-rule-help/#reason-keyword","title":"Reason keyword","text":"<p>The <code>Reason</code> keyword sets the reason the rule failed when using <code>Invoke-PSRule</code> and <code>Assert-PSRule</code>. The reason is only included in detailed output if the rule did not pass. If the rule passed, then reason is empty it returned output.</p> <p>Reasons are not included in the default view when using <code>Invoke-PSRule</code>. Use <code>-OutputFormat Wide</code> to display reason messages.</p> <p>To set a reason use the <code>Reason</code> keyword followed by the reason. For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend $LocalizedData.RecommendNameLabel\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n    Reason 'The standard name label is not set.'\n}\n</code></pre> <p>The <code>Reason</code> keyword can be used multiple times within conditional logic to return a list of reasons the rule failed. Additionally the reason messages can be localized by using the <code>$LocalizedData</code> variable.</p> <p>For example:</p> PowerShell<pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Recommend $LocalizedData.RecommendNameLabel\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n    # $LocalizedData.ReasonLabelMissing is set to 'The standard {0} label is not set.'.\n    Reason ($LocalizedData.ReasonLabelMissing -f 'name')\n}\n</code></pre>"},{"location":"authoring/writing-rule-help/#writing-markdown-documentation","title":"Writing markdown documentation","text":"<p>In addition to inline help, documentation can be written in markdown to provide online and offline help. Extended documentation is generally easier to author using markdown. Additionally markdown documentation is easily localized.</p> <p>Markdown documentation is authored by creating one or more <code>.md</code> files, one for each rule. PSRule uses a naming convention with a file name the same as the rule to match rule to markdown.</p> <p>For example, <code>metadata.Name.md</code> would be used for a rule named <code>metadata.Name</code>.</p> <p>We recommend matching the rule name case exactly when naming markdown files. This is because some file systems are case-sensitive. For example on Linux <code>Metadata.Name.md</code> would not match.</p> <p>Within each markdown file a number of predefined sections are automatically interpreted by PSRule. While it is possible to have additional sections, they will be ignored by the help system.</p> <p>The basic structure of markdown help is as follows:</p> <pre><code>---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n## SYNOPSIS\n\n{{ A brief summary of the rule }}\n\n## DESCRIPTION\n\n{{ A detailed description of the rule }}\n\n## RECOMMENDATION\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## NOTES\n\n{{ Additional information or configuration options }}\n\n## LINKS\n\n{{ Links to external references }}\n</code></pre> <p>The PSRule Visual Studio Code extension includes snippets for writing markdown documentation.</p>"},{"location":"authoring/writing-rule-help/#annotations","title":"Annotations","text":"<p>The annotation front matter at the top of the markdown document, is a set of key value pairs. Front matter follows YAML conventions and must start on the first line of the markdown document.</p> <p>A <code>---</code> on a separate line indicates the start and end of the front matter block. Within the front matter block, all key value pairs are treated as annotations by PSRule.</p> <p>Annotations are optional metadata that are associated with the rule. Any annotations associated with a rule are included in output. Some examples of annotations include; <code>severity</code>, <code>category</code>, <code>author</code>.</p> <p>Annotations differ from tags in two key ways:</p> <ul> <li>Annotations are localized, and can have a different value for different languages; tags are not.</li> <li>Tags are indexed and can be used to filter rules; annotations have no affect on rule filtering.</li> </ul> <p>The following reserved annotation exists:</p> <ul> <li><code>online version</code> - A URL to the online version of the document, used by <code>Get-PSRuleHelp -Online</code>.</li> </ul> <pre><code>---\nonline version: https://github.com/microsoft/PSRule/blob/main/docs/scenarios/rule-docs/rule-docs.md\n---\n</code></pre> <p>The front matter start and end <code>---</code> are not required and can be removed if no annotations are defined.</p>"},{"location":"authoring/writing-rule-help/#display-name","title":"Display name","text":"<p>The document title, indicated by a level one heading <code>#</code> is the display name of the rule. The rule display name is shown when using <code>Get-PSRuleHelp</code> and is included in output.</p> <p>Specify the display name on a single line. Wrapping the display name across multiple lines is not supported.</p> <p>For example:</p> <pre><code># Use recommended name label\n</code></pre>"},{"location":"authoring/writing-rule-help/#synopsis-section","title":"Synopsis section","text":"<p>The synopsis section is indicated by the heading <code>## SYNOPSIS</code>. Any text following the heading is interpreted by PSRule and included in output. The synopsis is displayed when using <code>Get-PSRule</code> and <code>Get-PSRuleHelp</code> cmdlets.</p> <p>The synopsis is intended to be a brief description of the rule, over a single line. A good synopsis should convey the purpose of the rule. A more verbose description can be included in the description section.</p> <p>For example:</p> <pre><code>## SYNOPSIS\n\nDeployments and services must use the app.kubernetes.io/name label.\n</code></pre>"},{"location":"authoring/writing-rule-help/#description-section","title":"Description section","text":"<p>The description section is indicated by the heading <code>## DESCRIPTION</code>. Any text following the heading is interpreted by PSRule and included in output. The description is displayed when using the <code>Get-PSRuleHelp</code> cmdlet.</p> <p>The description is intended to be a verbose description of the rule. If your rule documentation needs to include background information include it here.</p> <p>PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.</p> <p>For example:</p> <pre><code>## DESCRIPTION\n\nKubernetes defines a common set of labels that are recommended for tool interoperability.\nThese labels should be used to consistently apply standard metadata.\n\nThe `app.kubernetes.io/name` label should be used to specify the name of the application.\n</code></pre>"},{"location":"authoring/writing-rule-help/#recommendation-section","title":"Recommendation section","text":"<p>The recommendation section is indicated by the heading <code>## RECOMMENDATION</code>. Any text following the heading is interpreted by PSRule and included in output. The recommendation is displayed when using the <code>Invoke-PSRule</code> and <code>Get-PSRuleHelp</code> cmdlets.</p> <p>The recommendation is intended to identify corrective actions that can be taken to address any failures. Avoid using URLs within the recommendation. Use the links section to include references to external sources.</p> <p>PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.</p> <p>For example:</p> <pre><code>## RECOMMENDATION\n\nConsider setting the recommended label `app.kubernetes.io/name` on deployment and service resources.\n</code></pre>"},{"location":"authoring/writing-rule-help/#notes-section","title":"Notes section","text":"<p>The notes section is indicated by the heading <code>## NOTES</code>. Any text following the heading is interpreted by PSRule and included in pipeline output. Notes are excluded when formatting output as YAML and JSON.</p> <p>To view any included notes use the <code>Get-PSRuleHelp</code> cmdlet with the <code>-Full</code> switch.</p> <p>Use notes to include additional information such configuration options.</p> <p>PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.</p> <p>For example:</p> <pre><code>## NOTES\n\nThe Kubernetes recommended labels include:\n\n- `app.kubernetes.io/name`\n- `app.kubernetes.io/instance`\n- `app.kubernetes.io/version`\n- `app.kubernetes.io/component`\n- `app.kubernetes.io/part-of`\n- `app.kubernetes.io/managed-by`\n</code></pre>"},{"location":"authoring/writing-rule-help/#links-section","title":"Links section","text":"<p>The links section is indicated by the heading <code>## LINKS</code>. Any markdown links following the heading are interpreted by PSRule and included in pipeline output. Links are excluded when formatting output as YAML and JSON.</p> <p>To view any included links use the <code>Get-PSRuleHelp</code> cmdlet with the <code>-Full</code> switch.</p> <p>Use links to reference external sources with a URL.</p> <p>To specify links, use the markdown syntax <code>[display name](url)</code>. Include each link on a separate line. To improve display in web rendered markdown, use a list of links by prefixing the line with <code>-</code>.</p> <p>Additional text such as <code>See additional information:</code> is useful for web rendered views, but ignored by PSRule.</p> <p>For example:</p> <pre><code>## LINKS\n\n- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)\n</code></pre>"},{"location":"authoring/writing-rule-help/#localizing-documentation-files","title":"Localizing documentation files","text":"<p>When distributing rules, you may need to provide rule help in different languages. PSRule builds on the culture system in PowerShell.</p>"},{"location":"authoring/writing-rule-help/#using-cultures","title":"Using cultures","text":"<p>A directory structure is used to identify the markdown documentation that should be used for each culture.</p> <p>To get a list of cultures in PowerShell the use cmdlet <code>Get-Culture -ListAvailable</code>.</p> <p>For example, store documentation targeted to the culture <code>en-US</code> in a directory named <code>en-US</code>. Similarly, documentation for cultures such as <code>en-AU</code>, <code>en-GB</code> and <code>fr-FR</code> would be in separate directories.</p> <p>If a directory for the exact culture <code>en-US</code> doesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory named <code>en</code>.</p> <p>When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux <code>en-us</code> would not match.</p>"},{"location":"authoring/writing-rule-help/#culture-directory-search-path","title":"Culture directory search path","text":"<p>The path that PSRule looks for a culture directory in varies depending on how the rule is redistributed. Rules can be redistributed individually (loose) or included in a module.</p> <p>The following logic is used to locate the culture directory.</p> <ul> <li>If the rules are loose, PSRule will search for the culture directory in the same subdirectory as the <code>.Rule.ps1</code> file.</li> <li>When rules are included in a module, PSRule will search for the culture directory in the same subdirectory as the module manifest .psd1 file.</li> </ul> <p>For example, loose file structure:</p> <ul> <li>.ps-rule/<ul> <li>en/<ul> <li>metadata.Name.md</li> </ul> </li> <li>en-US/<ul> <li>metadata.Name.md</li> </ul> </li> <li>fr-FR/<ul> <li>metadata.Name.md</li> </ul> </li> <li>kubernetes.Rule.ps1</li> </ul> </li> </ul> <p>Module file structure:</p> <ul> <li>Kubernetes.Rules/<ul> <li>en/<ul> <li>metadata.Name.md</li> </ul> </li> <li>en-US/<ul> <li>metadata.Name.md</li> </ul> </li> <li>fr-FR/<ul> <li>metadata.Name.md</li> </ul> </li> <li>rules/<ul> <li>kubernetes.Rule.ps1</li> </ul> </li> <li>Kubernetes.Rules.psd1</li> </ul> </li> </ul>"},{"location":"authoring/writing-rule-help/#more-information","title":"More information","text":"<ul> <li>kubernetes.Rule.ps1 - An example rule for validating name label.</li> <li>metadata.Name - An example markdown documentation file.</li> </ul>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/","title":"Use mandatory tags","text":""},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#synopsis","title":"SYNOPSIS","text":"<p>Each resource must be tagged with mandatory tags.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#description","title":"DESCRIPTION","text":"<p>Azure resources can be tagged with additional metadata. Our enterprise standard requires that the following tags are used:</p> <ul> <li>Environment</li> <li>BusinessUnit</li> <li>Department</li> <li>CostCode</li> </ul>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#recommendation","title":"RECOMMENDATION","text":"<p>Consider tagging Azure resource with mandatory tags.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#links","title":"LINKS","text":"<ul> <li>Use tags to organize your Azure resources and management hierarchy</li> </ul>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/","title":"Enforce encrypted Storage connections","text":""},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#synopsis","title":"SYNOPSIS","text":"<p>Storage accounts should only accept encrypted connections.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#description","title":"DESCRIPTION","text":"<p>An Azure Storage Account is configured to allow unencrypted connections. This does not indicate that unencrypted connections are being used.</p> <p>Unencrypted communication to storage accounts could allow disclosure of information to an untrusted party.</p> <p>Storage Accounts can be configured to require encrypted connections, by setting the Secure transfer required option. If secure transfer required is not enabled (the default), unencrypted and encrypted connections are permitted.</p> <p>When secure transfer required is enabled, attempts to connect to storage using HTTP or unencrypted SMB connections are rejected.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#recommendation","title":"RECOMMENDATION","text":"<p>Storage accounts should only accept secure traffic. Consider setting secure transfer required if there is no requirement to access storage over unencrypted connections. Also consider using Azure Policy to audit or enforce this configuration.</p>"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#links","title":"LINKS","text":"<ul> <li>Require secure transfer in Azure Storage</li> <li>Sample policy for ensuring https traffic</li> </ul>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/","title":"Use recommended name label","text":""},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#synopsis","title":"SYNOPSIS","text":"<p>Deployments and services must use the app.kubernetes.io/name label.</p>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#description","title":"DESCRIPTION","text":"<p>Kubernetes defines a common set of labels that are recommended for tool interoperability. These labels should be used to consistently apply standard metadata.</p> <p>The <code>app.kubernetes.io/name</code> label should be used to specify the name of the application.</p>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#recommendation","title":"RECOMMENDATION","text":"<p>Consider setting the recommended label <code>app.kubernetes.io/name</code> on deployment and service resources.</p>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#notes","title":"NOTES","text":"<p>The Kubernetes recommended labels include:</p> <ul> <li><code>app.kubernetes.io/name</code></li> <li><code>app.kubernetes.io/instance</code></li> <li><code>app.kubernetes.io/version</code></li> <li><code>app.kubernetes.io/component</code></li> <li><code>app.kubernetes.io/part-of</code></li> <li><code>app.kubernetes.io/managed-by</code></li> </ul>"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#links","title":"LINKS","text":"<ul> <li>Recommended Labels</li> </ul>"},{"location":"commands/PSRule/en-US/Assert-PSRule/","title":"Assert-PSRule","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#synopsis","title":"SYNOPSIS","text":"<p>Evaluate objects against matching rules and assert any failures.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#input-default","title":"Input (Default)","text":"<pre><code>Assert-PSRule [-Module &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [-Convention &lt;String[]&gt;] [-Style &lt;OutputStyle&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-OutputPath &lt;String&gt;]\n [-OutputFormat &lt;OutputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;]\n [-Culture &lt;String[]&gt;] -InputObject &lt;PSObject&gt; [-ResultVariable &lt;String&gt;] [-WhatIf] [-Confirm]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputpath","title":"InputPath","text":"<pre><code>Assert-PSRule -InputPath &lt;String[]&gt; [-Module &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [-Convention &lt;String[]&gt;] [-Style &lt;OutputStyle&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-OutputPath &lt;String&gt;]\n [-OutputFormat &lt;OutputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;]\n [-Culture &lt;String[]&gt;] [-ResultVariable &lt;String&gt;] [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#description","title":"DESCRIPTION","text":"<p>Evaluate objects against matching rules and assert any failures. Objects can be specified directly from the pipeline or provided from file.</p> <p>The commands <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> provide similar functionality, as differ as follows:</p> <ul> <li><code>Invoke-PSRule</code> writes results as structured objects</li> <li><code>Assert-PSRule</code> writes results as a formatted string.</li> </ul>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-1","title":"Example 1","text":"<pre><code>@{ Name = 'Item 1' } | Assert-PSRule;\n</code></pre> <p>Evaluate a simple hashtable on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-2","title":"Example 2","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n</code></pre> <pre><code>-&gt; Fridge : System.Management.Automation.PSCustomObject\n\n   [FAIL] isFruit\n\n-&gt; Apple : System.Management.Automation.PSCustomObject\n\n   [PASS] isFruit\n\nAssert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n+          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo          : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\n</code></pre> <p>Evaluate an array of objects on the pipeline against rules loaded a specified relative path.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-3","title":"Example 3","text":"<pre><code>$items | Assert-PSRule -Module PSRule.Rules.Azure -o NUnit3 -OutputPath .\\reports\\results.xml\n</code></pre> <p>Evaluate items from a pre-installed rules module PSRule.Rules.Azure. Additionally save the results as a NUnit report.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-4","title":"Example 4","text":"<pre><code>$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\ -ResultVariable resultRecords;\n</code></pre> <p>Evaluate items and additionally save the results into a variable <code>resultRecords</code>.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>When this option is set to <code>File</code> PSRule scans the path and subdirectories specified by <code>-InputPath</code>. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-baseline","title":"-Baseline","text":"<p>Specifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.</p> <pre><code>Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-convention","title":"-Convention","text":"<p>Specifies conventions by name to execute in the pipeline when processing objects.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-name","title":"-Name","text":"<p>The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-targettype","title":"-TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>This parameter if set, overrides the <code>Input.TargetType</code> option.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option. For details see the about_PSRule_Options help topic.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputpath","title":"-OutputPath","text":"<p>Specifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is written. This parameter has no affect when <code>-OutputPath</code> is not specified.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> <li>Markdown - Output is serialized as Markdown.</li> <li>NUnit3 - Output is serialized as NUnit3 (XML).</li> <li>Csv - Output is serialized as a comma separated values (CSV).</li> <li>Sarif - Output is serialized as SARIF.</li> </ul> <p>The <code>Wide</code> format is not applicable to <code>Assert-PSRule</code>.</p> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-style","title":"-Style","text":"<p>Configures the style that results will be presented in.</p> <p>The following styles are available:</p> <ul> <li>Client - Output is written to the host directly in green/ red to indicate outcome.</li> <li>Plain - Output is written as an unformatted string. This option can be redirected to a file.</li> <li>AzurePipelines - Output is written for integration Azure Pipelines.</li> <li>GitHubActions - Output is written for integration GitHub Actions.</li> <li>VisualStudioCode - Output is written for integration with Visual Studio Code.</li> <li>Detect - Output style will be detected by checking the environment variables. This is the default.</li> </ul> <p>Detect uses the following logic:</p> <ol> <li>If the <code>TF_BUILD</code> environment variable is set to <code>true</code>, <code>AzurePipelines</code> will be used.</li> <li>If the <code>GITHUB_ACTIONS</code> environment variable is set to <code>true</code>, <code>GitHubActions</code> will be used.</li> <li>If the <code>TERM_PROGRAM</code> environment variable is set to <code>vscode</code>, <code>VisualStudioCode</code> will be used.</li> <li>Use <code>Client</code>.</li> </ol> <p>Each of these styles outputs to the host. To capture output as a string redirect the information stream. For example: <code>6&gt;&amp;1</code></p> <pre><code>Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions, VisualStudioCode, Detect\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-as","title":"-As","text":"<p>The type of results to produce. Detailed results are generated by default.</p> <p>The following result formats are available:</p> <ul> <li><code>Detail</code> - Returns pass/ fail results for each rule per object.</li> <li><code>Summary</code> - Failure or errors are shown but passing results are summarized.</li> </ul> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outcome","title":"-Outcome","text":"<p>Filter output to only show rule results with a specific outcome.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-resultvariable","title":"-ResultVariable","text":"<p>Stores output result objects in the specified variable.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"<p>You can pipe any object to Assert-PSRule.</p>"},{"location":"commands/PSRule/en-US/Assert-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemstring","title":"System.String","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRule</p> <p>Invoke-PSRule</p> <p>Test-PSRuleTarget</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/","title":"Export-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"<p>Exports a list of baselines.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#syntax","title":"SYNTAX","text":"<pre><code>Export-PSRuleBaseline [-Module &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Option &lt;PSRuleOption&gt;]\n [-Culture &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] -OutputPath &lt;String&gt; [-OutputEncoding &lt;OutputEncoding&gt;]\n [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#description","title":"DESCRIPTION","text":"<p>Exports a list of baselines to a file.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#example-1","title":"Example 1","text":"<pre><code>Export-PSRuleBaseline -Module PSRule.Rules.Azure -OutputFormat Yaml -OutputPath Baseline.Rule.yml\n</code></pre> <p>Exports list of baselines from <code>PSRule.Rules.Azure</code> module to file <code>Baseline.Rule.yml</code> in YAML output format.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-module","title":"-Module","text":"<p>Search for baselines definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-path","title":"-Path","text":"<p>One or more paths to search for baselines within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-name","title":"-Name","text":"<p>The name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>Yaml - Output is serialized as YAML. This is the default.</li> <li>Json - Output is serialized as JSON.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: Yaml\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputencoding","title":"-OutputEncoding","text":"<p>Sets the option <code>Output.Encoding</code>. The <code>Output.Encoding</code> option configured the encoding used to write results to file.</p> <pre><code>Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputpath","title":"-OutputPath","text":"<p>Sets the option <code>Output.Path</code>. The <code>Output.Path</code> option configures the output path the results are written to.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRuleBaseline</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/","title":"Get-PSRule","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#synopsis","title":"SYNOPSIS","text":"<p>Get a list of rule definitions.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#syntax","title":"SYNTAX","text":"<pre><code>Get-PSRule [-Module &lt;String[]&gt;] [-ListAvailable] [-OutputFormat &lt;OutputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;] [-Culture &lt;String&gt;]\n [-IncludeDependencies] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#description","title":"DESCRIPTION","text":"<p>Get a list of matching rule definitions within the search path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#example-1","title":"Example 1","text":"<pre><code>Get-PSRule;\n</code></pre> <pre><code>RuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nisFruit                                                        An example rule\n</code></pre> <p>Get a list of rule definitions from the current working path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-2","title":"Example 2","text":"<pre><code>Get-PSRule -Module PSRule.Rules.Azure;\n</code></pre> <pre><code>RuleName                            ModuleName                 Synopsis\n--------                            ----------                 --------\nAzure.ACR.AdminUser                 PSRule.Rules.Azure         Use Azure AD accounts instead of using the registry adm\u2026\nAzure.ACR.MinSku                    PSRule.Rules.Azure         ACR should use the Premium or Standard SKU for producti\u2026\nAzure.AKS.MinNodeCount              PSRule.Rules.Azure         AKS clusters should have minimum number of nodes for fa\u2026\nAzure.AKS.Version                   PSRule.Rules.Azure         AKS clusters should meet the minimum version.\nAzure.AKS.UseRBAC                   PSRule.Rules.Azure         AKS cluster should use role-based access control (RBAC).\n</code></pre> <p>Get a list of rule definitions included in the module <code>PSRule.Rules.Azure</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-3","title":"Example 3","text":"<pre><code>Get-PSRule -Module PSRule.Rules.Azure -OutputFormat Wide;\n</code></pre> <pre><code>RuleName                            ModuleName                 Synopsis                     Tag\n--------                            ----------                 --------                     ---\nAzure.ACR.AdminUser                 PSRule.Rules.Azure         Use Azure AD accounts        severity='Critical'\n                                                               instead of using the         category='Security\n                                                               registry admin user.         configuration'\nAzure.ACR.MinSku                    PSRule.Rules.Azure         ACR should use the Premium   severity='Important'\n                                                               or Standard SKU for          category='Performance'\n                                                               production deployments.\nAzure.AKS.MinNodeCount              PSRule.Rules.Azure         AKS clusters should have     severity='Important'\n                                                               minimum number of nodes for  category='Reliability'\n                                                               failover and updates.\nAzure.AKS.Version                   PSRule.Rules.Azure         AKS clusters should meet     severity='Important'\n                                                               the minimum version.         category='Operations\n                                                                                            management'\nAzure.AKS.UseRBAC                   PSRule.Rules.Azure         AKS cluster should use       severity='Important'\n                                                               role-based access control    category='Security\n                                                               (RBAC).                      configuration'\n</code></pre> <p>Get a list of rule definitions included in the module <code>PSRule.Rules.Azure</code> including tags with line wrapping.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#-name","title":"-Name","text":"<p>The name of a specific rule to list. If this parameter is not specified all rules in search paths will be listed.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-listavailable","title":"-ListAvailable","text":"<p>Look for modules containing rule definitions including modules that are currently not imported.</p> <p>This switch is used with the <code>-Module</code> parameter.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Wide - Output is presented using the wide table format, which includes tags and wraps columns.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Wide, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-includedependencies","title":"-IncludeDependencies","text":"<p>When this switch is specified, dependencies of the rules that meet the <code>-Name</code> and <code>-Tag</code> filters are included even if they would normally be excluded.</p> <p>This switch has no affect when getting an unfiltered list of rules.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#-baseline","title":"-Baseline","text":"<p>When specified, rules are filtered so that only rules that are included in the baselines are returned.</p> <pre><code>Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRule/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#psruledefinitionsrulesirulev1","title":"PSRule.Definitions.Rules.IRuleV1","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#related-links","title":"RELATED LINKS","text":"<p>Invoke-PSRule</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/","title":"Get-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"<p>Get a list of baselines.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#syntax","title":"SYNTAX","text":"<pre><code>Get-PSRuleBaseline [-Module &lt;String[]&gt;] [-ListAvailable] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;]\n [-Option &lt;PSRuleOption&gt;] [-Culture &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#description","title":"DESCRIPTION","text":"<p>Get a list of matching baselines within the search path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#example-1","title":"Example 1","text":"<pre><code>Get-PSRuleBaseline;\n</code></pre> <p>Get a list of baselines from the current working path.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-module","title":"-Module","text":"<p>Search for baselines definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-listavailable","title":"-ListAvailable","text":"<p>Look for modules containing baselines including modules that are currently not imported.</p> <p>This switch is used with the <code>-Module</code> parameter.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-path","title":"-Path","text":"<p>One or more paths to search for baselines within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-name","title":"-Name","text":"<p>The name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#psruledefinitionsbaseline","title":"PSRule.Definitions.Baseline","text":"<p>This is the default.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#systemstring","title":"System.String","text":"<p>When you use <code>-OutputFormat Yaml</code> or <code>-OutputFormat Json</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRule</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/","title":"Get-PSRuleHelp","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#synopsis","title":"SYNOPSIS","text":"<p>Displays information about a rule.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#syntax","title":"SYNTAX","text":"<pre><code>Get-PSRuleHelp [-Module &lt;String&gt;] [-Online] [-Full] [[-Name] &lt;String[]&gt;] [-Path &lt;String&gt;]\n [-Option &lt;PSRuleOption&gt;] [-Culture &lt;String&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#description","title":"DESCRIPTION","text":"<p>The <code>Get-PSRuleHelp</code> cmdlet display information about a rule.</p> <p>By default, this cmdlet will look for rules in the current path and loaded modules. To get help for a specific rule or module use the <code>-Name</code> or <code>-Module</code> parameters.</p> <p>If the rule has an online version of the documentation, use the <code>-Online</code> parameter to view it in your default web browser.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-1","title":"Example 1","text":"<pre><code>Get-PSRuleHelp;\n</code></pre> <p>Get a list of rule help within the current path or loaded modules.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-2","title":"Example 2","text":"<pre><code>Get-PSRuleHelp Azure.ACR.AdminUser;\n</code></pre> <p>Get rule documentation for the rule <code>Azure.ACR.AdminUser</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-3","title":"Example 3","text":"<pre><code>Get-PSRuleHelp Azure.ACR.AdminUser -Online;\n</code></pre> <p>Browse to the online version of documentation for <code>Azure.ACR.AdminUser</code> using the default web browser.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-name","title":"-Name","text":"<p>The name of the rule to get documentation for.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-path","title":"-Path","text":"<p>A path to check documentation for. By default, help from the current working path and loaded modules is listed. Results can be filtered by using <code>-Name</code>, <code>-Path</code> or <code>-Module</code>.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-module","title":"-Module","text":"<p>Limit returned information to rules in the specified module. By default, help from the current working path and loaded modules is listed. Results can be filtered by using <code>-Name</code>, <code>-Path</code> or <code>-Module</code>.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-online","title":"-Online","text":"<p>Instead of displaying documentation within PowerShell, browse to the online version using the default web browser.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-full","title":"-Full","text":"<p>Display additional information such as notes and links.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#psrulerulesrulehelpinfo","title":"PSRule.Rules.RuleHelpInfo","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/","title":"Get-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"<p>Get a list of target objects.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#input-default","title":"Input (Default)","text":"<pre><code>Get-PSRuleTarget [-Format &lt;InputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;]\n -InputObject &lt;PSObject&gt; [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputpath","title":"InputPath","text":"<pre><code>Get-PSRuleTarget -InputPath &lt;String[]&gt; [-Format &lt;InputFormat&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;]\n [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#description","title":"DESCRIPTION","text":"<p>Get a list of target objects from input.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#example-1","title":"Example 1","text":"<pre><code>Get-PSRuleTarget -InputPath .\\resources.json;\n</code></pre> <p>Get target objects from <code>resources.json</code>.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/","title":"Invoke-PSRule","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#synopsis","title":"SYNOPSIS","text":"<p>Evaluate objects against matching rules and output the results.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#input-default","title":"Input (Default)","text":"<pre><code>Invoke-PSRule [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;] [-Format &lt;InputFormat&gt;]\n [-OutputPath &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-Baseline &lt;BaselineOption&gt;] [-Convention &lt;String[]&gt;]\n [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;]\n [-TargetType &lt;String[]&gt;] [-Culture &lt;String[]&gt;] -InputObject &lt;PSObject&gt; [-WhatIf] [-Confirm]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputpath","title":"InputPath","text":"<pre><code>Invoke-PSRule -InputPath &lt;String[]&gt; [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-As &lt;ResultFormat&gt;]\n [-Format &lt;InputFormat&gt;] [-OutputPath &lt;String&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-Baseline &lt;BaselineOption&gt;]\n [-Convention &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;]\n [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;] [-Culture &lt;String[]&gt;] [-WhatIf] [-Confirm]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#description","title":"DESCRIPTION","text":"<p>Evaluate objects against matching rules and output the results. Objects can be specified directly from the pipeline or provided from file.</p> <p>The commands <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> provide similar functionality, as differ as follows:</p> <ul> <li><code>Invoke-PSRule</code> writes results as structured objects</li> <li><code>Assert-PSRule</code> writes results as a formatted string.</li> </ul>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-1","title":"Example 1","text":"<pre><code>@{ Name = 'Item 1' } | Invoke-PSRule;\n</code></pre> <p>Evaluate a simple hashtable on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-2","title":"Example 2","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\n</code></pre> <pre><code>TargetName: Fridge\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Fail       Fruit is only Apple, Orange and Pear\n\n\n   TargetName: Apple\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Pass       Fruit is only Apple, Orange and Pear\n</code></pre> <p>Evaluate an array of objects on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-3","title":"Example 3","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and only return failing results\n$items | Invoke-PSRule -Outcome Fail;\n</code></pre> <pre><code>TargetName: Fridge\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Fail       Fruit is only Apple, Orange and Pear\n</code></pre> <p>Evaluate an array of objects, only failing object results are returned.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-4","title":"Example 4","text":"<pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and show rule summary\n$items | Invoke-PSRule -As Summary;\n</code></pre> <pre><code>RuleName                            Pass  Fail  Outcome\n--------                            ----  ----  -------\nisFruit                             1     1     Fail\n</code></pre> <p>Evaluate an array of objects. The results for each rule is returned as a summary. Outcome is represented as the worst outcome.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-name","title":"-Name","text":"<p>The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outcome","title":"-Outcome","text":"<p>Filter output to only show rule results with a specific outcome.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-as","title":"-As","text":"<p>The type of results to produce. Detailed results are generated by default.</p> <p>The following result formats are available:</p> <ul> <li><code>Detail</code> - Returns pass/ fail results for each rule per object.</li> <li><code>Summary</code> - Returns summarized results for the rule and the worst outcome.</li> </ul> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>When this option is set to <code>File</code> PSRule scans the path and subdirectories specified by <code>-InputPath</code>. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-baseline","title":"-Baseline","text":"<p>Specifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.</p> <pre><code>Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-convention","title":"-Convention","text":"<p>Specifies conventions by name to execute in the pipeline when processing objects.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-targettype","title":"-TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>This parameter if set, overrides the <code>Input.TargetType</code> option.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option. For details see the about_PSRule_Options help topic.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. If no sources are specified by <code>-Path</code>, <code>-Module</code>, or options, the current working directory is used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputpath","title":"-OutputPath","text":"<p>Specifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputformat","title":"-OutputFormat","text":"<p>Configures the format that output is presented in.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults. This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> <li>Markdown - Output is serialized as Markdown.</li> <li>NUnit3 - Output is serialized as NUnit3 (XML).</li> <li>Csv - Output is serialized as a comma separated values (CSV).</li> <li>Wide - Output is presented using the wide table format, which includes reason and wraps columns.</li> <li>Sarif - Output is serialized as SARIF.</li> </ul> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"<p>You can pipe any object to Invoke-PSRule.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulerecord","title":"PSRule.Rules.RuleRecord","text":"<p>This is the default.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulesummaryrecord","title":"PSRule.Rules.RuleSummaryRecord","text":"<p>When you use the <code>-As Summary</code>. Otherwise, it returns a <code>RuleRecord</code> object.</p>"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#related-links","title":"RELATED LINKS","text":"<p>Get-PSRule</p> <p>Assert-PSRule</p> <p>Test-PSRuleTarget</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/","title":"New-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"<p>Create options to configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#frompath-default","title":"FromPath (Default)","text":"<pre><code>New-PSRuleOption [[-Path] &lt;String&gt;] [-Configuration &lt;ConfigurationOption&gt;]\n [-SuppressTargetName &lt;SuppressionOption&gt;] [-BindTargetName &lt;BindTargetName[]&gt;]\n [-BindTargetType &lt;BindTargetName[]&gt;] [-BaselineGroup &lt;Hashtable&gt;] [-BindingIgnoreCase &lt;Boolean&gt;]\n [-BindingField &lt;Hashtable&gt;] [-BindingNameSeparator &lt;String&gt;] [-BindingPreferTargetInfo &lt;Boolean&gt;]\n [-TargetName &lt;String[]&gt;] [-TargetType &lt;String[]&gt;] [-BindingUseQualifiedName &lt;Boolean&gt;]\n [-Convention &lt;String[]&gt;] [-DuplicateResourceId &lt;ExecutionActionPreference&gt;]\n [-InitialSessionState &lt;SessionState&gt;] [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;] [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;]\n [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreRepositoryCommon &lt;Boolean&gt;] [-InputIgnoreObjectSource &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputTargetType &lt;String[]&gt;]\n [-InputPathIgnore &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromoption","title":"FromOption","text":"<pre><code>New-PSRuleOption [-Option] &lt;PSRuleOption&gt; [-Configuration &lt;ConfigurationOption&gt;]\n [-SuppressTargetName &lt;SuppressionOption&gt;] [-BindTargetName &lt;BindTargetName[]&gt;]\n [-BindTargetType &lt;BindTargetName[]&gt;] [-BaselineGroup &lt;Hashtable&gt;] [-BindingIgnoreCase &lt;Boolean&gt;]\n [-BindingField &lt;Hashtable&gt;] [-BindingNameSeparator &lt;String&gt;] [-BindingPreferTargetInfo &lt;Boolean&gt;]\n [-TargetName &lt;String[]&gt;] [-TargetType &lt;String[]&gt;] [-BindingUseQualifiedName &lt;Boolean&gt;]\n [-Convention &lt;String[]&gt;] [-DuplicateResourceId &lt;ExecutionActionPreference&gt;]\n [-InitialSessionState &lt;SessionState&gt;] [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;] [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;]\n [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreRepositoryCommon &lt;Boolean&gt;] [-InputIgnoreObjectSource &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputTargetType &lt;String[]&gt;]\n [-InputPathIgnore &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromdefault","title":"FromDefault","text":"<pre><code>New-PSRuleOption [-Default] [-Configuration &lt;ConfigurationOption&gt;] [-SuppressTargetName &lt;SuppressionOption&gt;]\n [-BindTargetName &lt;BindTargetName[]&gt;] [-BindTargetType &lt;BindTargetName[]&gt;] [-BaselineGroup &lt;Hashtable&gt;]\n [-BindingIgnoreCase &lt;Boolean&gt;] [-BindingField &lt;Hashtable&gt;] [-BindingNameSeparator &lt;String&gt;]\n [-BindingPreferTargetInfo &lt;Boolean&gt;] [-TargetName &lt;String[]&gt;] [-TargetType &lt;String[]&gt;]\n [-BindingUseQualifiedName &lt;Boolean&gt;] [-Convention &lt;String[]&gt;]\n [-DuplicateResourceId &lt;ExecutionActionPreference&gt;] [-InitialSessionState &lt;SessionState&gt;]\n [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;] [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;] [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreRepositoryCommon &lt;Boolean&gt;] [-InputIgnoreObjectSource &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputTargetType &lt;String[]&gt;]\n [-InputPathIgnore &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#description","title":"DESCRIPTION","text":"<p>The New-PSRuleOption cmdlet creates an options object that can be passed to PSRule cmdlets to configure execution.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-1","title":"Example 1","text":"<pre><code>$option = New-PSRuleOption -Option @{ 'execution.mode' = 'ConstrainedLanguage' }\n@{ Name = 'Item 1' } | Invoke-PSRule -Option $option\n</code></pre> <p>Create an options object and run rules in constrained mode.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-2","title":"Example 2","text":"<pre><code>$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\n</code></pre> <p>Create an options object that suppresses <code>TestObject1</code> and <code>TestObject3</code> for a rule named <code>storageAccounts.UseHttps</code>.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-3","title":"Example 3","text":"<pre><code># Create a custom function that returns a TargetName string\n$bindFn = {\n    param ($TargetObject)\n\n    $otherName = $TargetObject.PSObject.Properties['OtherName'];\n\n    if ($otherName -eq $Null) {\n        return $Null\n    }\n\n    return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\n</code></pre> <p>Creates an options object that uses a custom function to bind the TargetName of an object.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-4","title":"Example 4","text":"<pre><code>$option = New-PSRuleOption -Configuration @{ 'appServiceMinInstanceCount' = 2 };\n</code></pre> <p>Create an options object that sets the <code>appServiceMinInstanceCount</code> baseline configuration option to <code>2</code>.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-option","title":"-Option","text":"<p>Additional options that configure execution. Option also accepts a hashtable to configure options. See about_PSRule_Options for more information.</p> <pre><code>Type: PSRuleOption\nParameter Sets: FromOption\nAliases:\n\nRequired: True\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-path","title":"-Path","text":"<p>The path to a YAML file containing options.</p> <p>Either a directory or file path can be specified. When a directory is used, <code>ps-rule.yaml</code> will be used as the file name.</p> <p>If the <code>-Path</code> parameter is specified and the file does not exist, an exception will be generated.</p> <pre><code>Type: String\nParameter Sets: FromPath\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-default","title":"-Default","text":"<p>When specified, defaults are used for any options not overridden.</p> <pre><code>Type: SwitchParameter\nParameter Sets: FromDefault\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppresstargetname","title":"-SuppressTargetName","text":"<p>Configures suppression for a list of objects by TargetName. SuppressTargetName also accepts a hashtable to configure rule suppression. See about_PSRule_Options for more information.</p> <pre><code>Type: SuppressionOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargetname","title":"-BindTargetName","text":"<p>Configures a custom function to use to bind TargetName of an object. See about_PSRule_Options for more information.</p> <pre><code>Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-configuration","title":"-Configuration","text":"<p>Configures a set of baseline configuration values that can be used in rule definitions instead of using hard coded values. Configuration also accepts a hashtable of configuration values as key/ value pairs. See about_PSRule_Options for more information.</p> <pre><code>Type: ConfigurationOption\nParameter Sets: (All)\nAliases: BaselineConfiguration\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"<p>Sets the option <code>Baseline.Group</code>. The option <code>Baseline.Group</code> allows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargettype","title":"-BindTargetType","text":"<p>Configures a custom function to use to bind TargetType of an object. See about_PSRule_Options for more information.</p> <pre><code>Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"<p>Sets the option <code>Binding.IgnoreCase</code>. The option <code>Binding.IgnoreCase</code> determines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingfield","title":"-BindingField","text":"<p>Sets the option <code>Binding.Field</code>. The option specified one or more custom field bindings. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"<p>Sets the option <code>Binding.NameSeparator</code>. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"<p>Sets the option <code>Binding.PreferTargetInfo</code>. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-convention","title":"-Convention","text":"<p>Sets the <code>Option.ConventionInclude</code> option. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targetname","title":"-TargetName","text":"<p>Sets the option <code>Binding.TargetName</code>. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targettype","title":"-TargetType","text":"<p>Sets the option <code>Binding.TargetType</code>. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"<p>Sets the option <code>Binding.UseQualifiedName</code>. This option specifies is qualified target names are used. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"<p>Sets the <code>Execution.AliasReference</code> option. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"<p>Sets the <code>Execution.InvariantCulture</code> option. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"<p>Sets the <code>Execution.RuleInconclusive</code> option. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"<p>Sets the <code>Execution.UnprocessedObject</code> option. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"<p>Sets the <code>Include.Module</code> option to include additional module sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includepath","title":"-IncludePath","text":"<p>Sets the <code>Include.Path</code> option to include additional standalone sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-format","title":"-Format","text":"<p>Sets the <code>Input.Format</code> option to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"<p>Sets the <code>Input.IgnoreGitPath</code> option to determine if files within the .git path are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"<p>Sets the <code>Input.IgnoreRepositoryCommon</code> option to determine if files common repository files are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"<p>Sets the option <code>Input.IgnoreUnchangedPath</code>. The <code>Input.IgnoreUnchangedPath</code> option determine if unchanged files are ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"<p>Sets the <code>Input.ObjectPath</code> option to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"<p>Sets the <code>Input.PathIgnore</code> option. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"<p>Sets the <code>Input.TargetType</code> option to only process objects with the specified TargetType. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"<p>Sets the option <code>Input.IgnoreObjectSource</code>. The <code>Input.IgnoreObjectSource</code> option determines if objects will be skipped if the source path has been ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"<p>Sets the <code>Logging.LimitDebug</code> option to limit debug messages to a list of named debug scopes. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"<p>Sets the <code>Logging.LimitVerbose</code> option to limit verbose messages to a list of named verbose scopes. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"<p>Sets the <code>Logging.RuleFail</code> option to generate an informational message for each rule fail. See about_PSRule_Options for more information.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"<p>Sets the <code>Logging.RulePass</code> option to generate an informational message for each rule pass. See about_PSRule_Options for more information.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputas","title":"-OutputAs","text":"<p>Sets the option <code>Output.As</code>. The <code>Output.As</code> option configures the type of results to produce, either detail or summary.</p> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"<p>Sets the option <code>Output.Banner</code>. The <code>Output.Banner</code> option configure information displayed with PSRule banner. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <pre><code>Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"<p>Sets the option <code>Output.Culture</code>. The <code>Output.Culture</code> option configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"<p>Sets the option <code>Output.Encoding</code>. The <code>Output.Encoding</code> option configured the encoding used to write results to file.</p> <pre><code>Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"<p>Sets the option <code>Output.Footer</code>. The <code>Output.Footer</code> option configures the information displayed for PSRule footer. See about_PSRule_Options for more information.</p> <pre><code>Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"<p>Sets the option <code>Output.Format</code>. The <code>Output.Format</code> option configures the format that results will be presented in. See about_PSRule_Options for more information.</p> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"<p>Set the option <code>Output.JobSummaryPath</code>. The <code>Output.JobSummaryPath</code> option configures the path to a job summary output file.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"<p>Sets the option <code>Output.JsonIndent</code>. The <code>Output.JsonIndent</code> option configures indentation for JSON output.</p> <p>This option only applies to <code>Get-PSRule</code>, <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> cmdlets.</p> <pre><code>Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"<p>Sets the <code>Output.Outcome</code> option. This option can be set to include or exclude output results. See about_PSRule_Options for more information.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputpath","title":"-OutputPath","text":"<p>Sets the option <code>Output.Path</code>. The <code>Output.Path</code> option configures an output file path to write results.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"<p>Sets the option <code>Option.SarifProblemsOnly</code>. The <code>Output.SarifProblemsOnly</code> option determines if SARIF output only includes fail and error outcomes.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"<p>Sets the option <code>Option.Style</code>. The <code>Output.Style</code> option configures the style that results will be presented in.</p> <p>This option only applies to <code>Assert-PSRule</code>.</p> <pre><code>Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"<p>Sets the option <code>Repository.BaseRef</code>. The <code>Repository.BaseRef</code> option sets the repository base ref used for comparisons of changed files.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"<p>Sets the option <code>Repository.Url</code>. The <code>Repository.Url</code> option sets the repository URL reported in output.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"<p>Sets the option <code>Rule.IncludeLocal</code>. The <code>Rule.IncludeLocal</code> option configures if local rules are automatically included. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"<p>Sets the option <code>Execution.DuplicateResourceId</code>. The <code>Execution.DuplicateResourceId</code> option determines how to handle duplicate resources identifiers during execution.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"<p>Sets the option <code>Execution.InitialSessionState</code>. The <code>Execution.InitialSessionState</code> option determines how the initial session state for executing PowerShell code is created.</p> <pre><code>Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"<p>Sets the option <code>Execution.RuleExcluded</code>. The <code>Execution.RuleExcluded</code> option determines how to handle excluded rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"<p>Sets the option <code>Execution.RuleSuppressed</code>. The <code>Execution.RuleSuppressed</code> option determines how to handle suppressed rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"<p>Sets the option <code>Execution.SuppressionGroupExpired</code>. The <code>Execution.SuppressionGroupExpired</code> option determines how to handle expired suppression groups.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#related-links","title":"RELATED LINKS","text":"<p>Invoke-PSRule</p> <p>Set-PSRuleOption</p>"},{"location":"commands/PSRule/en-US/PSRule/","title":"PSRule Module","text":""},{"location":"commands/PSRule/en-US/PSRule/#description","title":"Description","text":"<p>A PowerShell rules engine.</p>"},{"location":"commands/PSRule/en-US/PSRule/#psrule-cmdlets","title":"PSRule Cmdlets","text":""},{"location":"commands/PSRule/en-US/PSRule/#assert-psrule","title":"Assert-PSRule","text":"<p>Evaluate objects against matching rules and assert any failures.</p>"},{"location":"commands/PSRule/en-US/PSRule/#export-psrulebaseline","title":"Export-PSRuleBaseline","text":"<p>Exports a list of baselines to a file.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psrule","title":"Get-PSRule","text":"<p>Get a list of matching rule definitions within the search path.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulebaseline","title":"Get-PSRuleBaseline","text":"<p>Get a list of matching baselines within the search path.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulehelp","title":"Get-PSRuleHelp","text":"<p>Get documentation for a rule.</p>"},{"location":"commands/PSRule/en-US/PSRule/#get-psruletarget","title":"Get-PSRuleTarget","text":"<p>Get a list of target object.</p>"},{"location":"commands/PSRule/en-US/PSRule/#invoke-psrule","title":"Invoke-PSRule","text":"<p>Evaluate objects against matching rules and output the results.</p>"},{"location":"commands/PSRule/en-US/PSRule/#new-psruleoption","title":"New-PSRuleOption","text":"<p>Create options to configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/PSRule/#set-psruleoption","title":"Set-PSRuleOption","text":"<p>Set options to configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/PSRule/#test-psruletarget","title":"Test-PSRuleTarget","text":"<p>Evaluate pipeline objects against matching rules.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/","title":"Set-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"<p>Sets options that configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#syntax","title":"SYNTAX","text":"<pre><code>Set-PSRuleOption [[-Path] &lt;String&gt;] [-Option &lt;PSRuleOption&gt;] [-PassThru] [-Force] [-AllowClobber]\n [-BaselineGroup &lt;Hashtable&gt;] [-BindingIgnoreCase &lt;Boolean&gt;] [-BindingField &lt;Hashtable&gt;]\n [-BindingNameSeparator &lt;String&gt;] [-BindingPreferTargetInfo &lt;Boolean&gt;] [-TargetName &lt;String[]&gt;]\n [-TargetType &lt;String[]&gt;] [-BindingUseQualifiedName &lt;Boolean&gt;] [-Convention &lt;String[]&gt;]\n [-DuplicateResourceId &lt;ExecutionActionPreference&gt;] [-InitialSessionState &lt;SessionState&gt;]\n [-SuppressionGroupExpired &lt;ExecutionActionPreference&gt;] [-ExecutionRuleExcluded &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleSuppressed &lt;ExecutionActionPreference&gt;] [-ExecutionAliasReference &lt;ExecutionActionPreference&gt;]\n [-ExecutionRuleInconclusive &lt;ExecutionActionPreference&gt;]\n [-ExecutionInvariantCulture &lt;ExecutionActionPreference&gt;]\n [-ExecutionUnprocessedObject &lt;ExecutionActionPreference&gt;] [-IncludeModule &lt;String[]&gt;]\n [-IncludePath &lt;String[]&gt;] [-Format &lt;InputFormat&gt;] [-InputIgnoreGitPath &lt;Boolean&gt;]\n [-InputIgnoreObjectSource &lt;Boolean&gt;] [-InputIgnoreRepositoryCommon &lt;Boolean&gt;]\n [-InputIgnoreUnchangedPath &lt;Boolean&gt;] [-ObjectPath &lt;String&gt;] [-InputPathIgnore &lt;String[]&gt;]\n [-InputTargetType &lt;String[]&gt;] [-LoggingLimitDebug &lt;String[]&gt;] [-LoggingLimitVerbose &lt;String[]&gt;]\n [-LoggingRuleFail &lt;OutcomeLogStream&gt;] [-LoggingRulePass &lt;OutcomeLogStream&gt;] [-OutputAs &lt;ResultFormat&gt;]\n [-OutputBanner &lt;BannerFormat&gt;] [-OutputCulture &lt;String[]&gt;] [-OutputEncoding &lt;OutputEncoding&gt;]\n [-OutputFooter &lt;FooterFormat&gt;] [-OutputFormat &lt;OutputFormat&gt;] [-OutputJobSummaryPath &lt;String&gt;]\n [-OutputJsonIndent &lt;Int32&gt;] [-OutputOutcome &lt;RuleOutcome&gt;] [-OutputPath &lt;String&gt;]\n [-OutputSarifProblemsOnly &lt;Boolean&gt;] [-OutputStyle &lt;OutputStyle&gt;] [-RepositoryBaseRef &lt;String&gt;]\n [-RepositoryUrl &lt;String&gt;] [-RuleIncludeLocal &lt;Boolean&gt;] [-WhatIf] [-Confirm] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#description","title":"DESCRIPTION","text":"<p>Sets options that configure PSRule execution.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-1","title":"Example 1","text":"<pre><code>PS C:\\&gt; Set-PSRuleOption -OutputFormat Yaml;\n</code></pre> <p>Sets the <code>Output.Format</code> to <code>Yaml</code> for <code>ps-rule.yaml</code> in the current working path. If the <code>ps-rule.yaml</code> file exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-2","title":"Example 2","text":"<pre><code>PS C:\\&gt; Set-PSRuleOption -OutputFormat Yaml -Path .\\project-options.yaml;\n</code></pre> <p>Sets the <code>Output.Format</code> to <code>Yaml</code> for <code>project-options.yaml</code> in the current working path. If the <code>project-options.yaml</code> file exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-path","title":"-Path","text":"<p>The path to a YAML file where options will be set.</p> <p>Either a directory or file path can be specified. When a directory is used, <code>ps-rule.yaml</code> will be used as the file name.</p> <p>The file will be created if it does not exist. If the file already exists it will be merged with the existing options and overwritten.</p> <p>If the directory does not exist an error will be generated. To force the creation of the directory path use the <code>-Force</code> switch.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-option","title":"-Option","text":"<p>An options object to use.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-passthru","title":"-PassThru","text":"<p>Use this option to return the options object to the pipeline instead of saving to disk.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-force","title":"-Force","text":"<p>Force creation of directory path for Path parameter, when the directory does not already exist.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-allowclobber","title":"-AllowClobber","text":"<p>Overwrite YAML files that contain comments.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"<p>Sets the option <code>Baseline.Group</code>. The option <code>Baseline.Group</code> allows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"<p>Sets the option <code>Binding.IgnoreCase</code>. The option <code>Binding.IgnoreCase</code> determines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingfield","title":"-BindingField","text":"<p>Sets the option <code>Binding.Field</code>. The option specified one or more custom field bindings. See about_PSRule_Options for more information.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"<p>Sets the option <code>Binding.NameSeparator</code>. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"<p>Sets the option <code>Binding.PreferTargetInfo</code>. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-convention","title":"-Convention","text":"<p>Sets the <code>Option.ConventionInclude</code> option. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targetname","title":"-TargetName","text":"<p>Sets the option <code>Binding.TargetName</code>. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targettype","title":"-TargetType","text":"<p>Sets the option <code>Binding.TargetType</code>. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"<p>Sets the option <code>Binding.UseQualifiedName</code>. This option specifies is qualified target names are used. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"<p>Sets the <code>Execution.AliasReference</code> option. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"<p>Sets the <code>Execution.InvariantCulture</code> option. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"<p>Sets the <code>Execution.RuleInconclusive</code> option. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"<p>Sets the <code>Execution.UnprocessedObject</code> option. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"<p>Sets the <code>Include.Module</code> option to include additional module sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includepath","title":"-IncludePath","text":"<p>Sets the <code>Include.Path</code> option to include additional standalone sources. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-format","title":"-Format","text":"<p>Sets the <code>Input.Format</code> option to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"<p>Sets the <code>Input.IgnoreGitPath</code> option to determine if files within the .git path are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"<p>Sets the <code>Input.IgnoreRepositoryCommon</code> option to determine if files common repository files are ignored. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"<p>Sets the option <code>Input.IgnoreUnchangedPath</code>. The <code>Input.IgnoreUnchangedPath</code> option determine if unchanged files are ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"<p>Sets the <code>Input.ObjectPath</code> option to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"<p>Sets the <code>Input.PathIgnore</code> option. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"<p>Sets the <code>Input.TargetType</code> option to only process objects with the specified TargetType.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"<p>Sets the option <code>Input.IgnoreObjectSource</code>. The <code>Input.IgnoreObjectSource</code> option determines if objects will be skipped if the source path has been ignored.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"<p>Sets the <code>Logging.LimitDebug</code> option to limit debug messages to a list of named debug scopes.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"<p>Sets the <code>Logging.LimitVerbose</code> option to limit verbose messages to a list of named verbose scopes.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"<p>Sets the <code>Logging.RuleFail</code> option to generate an informational message for each rule fail.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"<p>Sets the <code>Logging.RulePass</code> option to generate an informational message for each rule pass.</p> <pre><code>Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputas","title":"-OutputAs","text":"<p>Sets the option <code>Output.As</code>. The <code>Output.As</code> option configures the type of results to produce, either detail or summary.</p> <pre><code>Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"<p>Sets the option <code>Output.Banner</code>. The <code>Output.Banner</code> option configure information displayed with PSRule banner. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <pre><code>Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"<p>Sets the option <code>Output.Culture</code>. The <code>Output.Culture</code> option configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"<p>Sets the option <code>Output.Encoding</code>. The <code>Output.Encoding</code> option configured the encoding used to write results to file.</p> <pre><code>Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"<p>Sets the option <code>Output.Footer</code>. The <code>Output.Footer</code> option configures the information displayed for PSRule footer. See about_PSRule_Options for more information.</p> <pre><code>Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"<p>Sets the option <code>Output.Format</code>. The <code>Output.Format</code> option configures the format that results will be presented in.</p> <pre><code>Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"<p>Set the option <code>Output.JobSummaryPath</code>. The <code>Output.JobSummaryPath</code> option configures the path to a job summary output file.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"<p>Sets the option <code>Output.JsonIndent</code>. The <code>Output.JsonIndent</code> option configures indentation for JSON output.</p> <p>This option only applies to <code>Get-PSRule</code>, <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> cmdlets.</p> <pre><code>Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"<p>Sets the <code>Output.Outcome</code> option. This option can be set to include or exclude output results. See about_PSRule_Options for more information.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputpath","title":"-OutputPath","text":"<p>Sets the option <code>Output.Path</code>. The <code>Output.Path</code> option configures an output file path to write results.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"<p>Sets the option <code>Option.SarifProblemsOnly</code>. The <code>Output.SarifProblemsOnly</code> option determines if SARIF output only includes fail and error outcomes.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"<p>Sets the option <code>Option.Style</code>. The <code>Output.Style</code> option configures the style that results will be presented in.</p> <p>This option only applies to <code>Assert-PSRule</code>.</p> <pre><code>Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-whatif","title":"-WhatIf","text":"<p>Shows what would happen if the cmdlet runs. The cmdlet is not run.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-confirm","title":"-Confirm","text":"<p>Prompts you for confirmation before running the cmdlet.</p> <pre><code>Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"<p>Sets the option <code>Repository.BaseRef</code>. The <code>Repository.BaseRef</code> option sets the repository base ref used for comparisons of changed files.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"<p>Sets the option <code>Repository.Url</code>. The <code>Repository.Url</code> option sets the repository URL reported in output.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"<p>Sets the option <code>Rule.IncludeLocal</code>. The <code>Rule.IncludeLocal</code> option configures if local rules are automatically included. See about_PSRule_Options for more information.</p> <pre><code>Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"<p>Sets the option <code>Execution.DuplicateResourceId</code>. The <code>Execution.DuplicateResourceId</code> option determines how to handle duplicate resources identifiers during execution.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"<p>Sets the option <code>Execution.InitialSessionState</code>. The <code>Execution.InitialSessionState</code> option determines how the initial session state for executing PowerShell code is created.</p> <pre><code>Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"<p>Sets the option <code>Execution.RuleExcluded</code>. The <code>Execution.RuleExcluded</code> option determines how to handle excluded rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"<p>Sets the option <code>Execution.RuleSuppressed</code>. The <code>Execution.RuleSuppressed</code> option determines how to handle suppressed rules.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"<p>Sets the option <code>Execution.SuppressionGroupExpired</code>. The <code>Execution.SuppressionGroupExpired</code> option determines how to handle expired suppression groups.</p> <pre><code>Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":"<p>When you use the <code>-PassThru</code> switch, an options object is returned to the pipeline.</p>"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#related-links","title":"RELATED LINKS","text":"<p>New-PSRuleOption</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/","title":"Test-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"<p>Pass or fail objects against matching rules.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#input-default","title":"Input (Default)","text":"<pre><code>Test-PSRuleTarget [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-Format &lt;InputFormat&gt;]\n [-Convention &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] -InputObject &lt;PSObject&gt;\n [-Option &lt;PSRuleOption&gt;] [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;] [-Culture &lt;String&gt;]\n [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputpath","title":"InputPath","text":"<pre><code>Test-PSRuleTarget -InputPath &lt;String[]&gt; [-Module &lt;String[]&gt;] [-Outcome &lt;RuleOutcome&gt;] [-Format &lt;InputFormat&gt;]\n [-Convention &lt;String[]&gt;] [[-Path] &lt;String[]&gt;] [-Name &lt;String[]&gt;] [-Tag &lt;Hashtable&gt;] [-Option &lt;PSRuleOption&gt;]\n [-ObjectPath &lt;String&gt;] [-TargetType &lt;String[]&gt;] [-Culture &lt;String&gt;] [&lt;CommonParameters&gt;]\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#description","title":"DESCRIPTION","text":"<p>Evaluate objects against matching rules and return an overall pass or fail for the object as <code>$True</code> (pass) or <code>$False</code> (fail).</p> <p>PSRule uses the following logic to determine overall pass or fail for an object:</p> <ul> <li>The object fails if:<ul> <li>Any rules fail or error.</li> <li>Any rules are inconclusive.</li> </ul> </li> <li>The object passes if:<ul> <li>No matching rules were found.</li> <li>All rules pass.</li> </ul> </li> </ul> <p>By default, objects that do match any rules are not returned in results. To return <code>$True</code> for these objects, use <code>-Outcome All</code>.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#example-1","title":"Example 1","text":"<pre><code>@{ Name = 'Item 1' } | Test-PSRuleTarget;\n</code></pre> <p>Evaluate a simple hashtable on the pipeline against rules loaded from the current working path.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-path","title":"-Path","text":"<p>One or more paths to search for rule definitions within.</p> <p>If the <code>-Module</code> parameter is used, rule definitions from the currently working path will not be included by default.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-name","title":"-Name","text":"<p>The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-outcome","title":"-Outcome","text":"<p>Filter output to only show pipeline objects with a specific outcome.</p> <pre><code>Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-tag","title":"-Tag","text":"<p>Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.</p> <p>When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of <code>*</code> may be used to filter rules to any rule with the tag set, regardless of tag value.</p> <p>An array of tag values can be used to match a rule with either value. i.e. <code>severity = important, critical</code> matches rules with a category of either <code>important</code> or <code>critical</code>.</p> <pre><code>Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputobject","title":"-InputObject","text":"<p>The pipeline object to process rules for.</p> <pre><code>Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-option","title":"-Option","text":"<p>Additional options that configure execution. A <code>PSRuleOption</code> can be created by using the <code>New-PSRuleOption</code> cmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.</p> <p>For more information on PSRule options see about_PSRule_Options.</p> <pre><code>Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-format","title":"-Format","text":"<p>Configures the input format for when a string is passed in as a target object.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to have PSRule deserialize the object.</p> <p>When the <code>-InputPath</code> parameter is used with a file path or URL. If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When <code>-InputPath</code> is not used, <code>Detect</code> is the same as <code>None</code>.</p> <p>When this option is set to <code>File</code> PSRule scans the path and subdirectories specified by <code>-InputPath</code>. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.</p> <p>See <code>about_PSRule_Options</code> for details.</p> <p>This parameter takes precedence over the <code>Input.Format</code> option if set.</p> <pre><code>Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, Repository, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-convention","title":"-Convention","text":"<p>Specifies conventions by name to execute in the pipeline when processing objects.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-culture","title":"-Culture","text":"<p>Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.</p> <p>This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.</p> <p>The PowerShell cmdlet <code>Get-Culture</code> shows the current culture of PowerShell.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"<p>The name of a property to use instead of the pipeline object. If the property specified by <code>ObjectPath</code> is a collection or an array, then each item in evaluated separately.</p> <pre><code>Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-targettype","title":"-TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>This parameter if set, overrides the <code>Input.TargetType</code> option.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option. For details see the about_PSRule_Options help topic.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-module","title":"-Module","text":"<p>Search for rule definitions within a module. When specified without the <code>-Path</code> parameter, only rule definitions in the module will be discovered.</p> <p>When both <code>-Path</code> and <code>-Module</code> are specified, rule definitions from both are discovered.</p> <pre><code>Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputpath","title":"-InputPath","text":"<p>Instead of processing objects from the pipeline, import objects file the specified file paths.</p> <pre><code>Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\n</code></pre>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"<p>This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"<p>You can pipe any object to Test-PSRuleTarget.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemboolean","title":"System.Boolean","text":"<p>Returns <code>$True</code> when the object passes and <code>$False</code> when the object fails.</p>"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#related-links","title":"RELATED LINKS","text":"<p>Invoke-PSRule</p> <p>Assert-PSRule</p> <p>Get-PSRule</p>"},{"location":"concepts/baselines/","title":"Baselines","text":"<p>Abstract</p> <p>A baseline is a set of rules and configuration options. You can define a named baseline to run a set of rules for a specific use case.</p> <p>Baselines cover two (2) main scenarios:</p> <ul> <li>Rules \u2014 PSRule supports running rules by name or tag.   However, when working with a large number of rules it is often easier to group and run rules based on a name.</li> <li>Configuration \u2014 A baseline allows you to run any included rules with a predefined configuration by name.</li> </ul>"},{"location":"concepts/baselines/#defining-baselines","title":"Defining baselines","text":"<p>A baseline is defined as a resource within YAML or JSON. Baselines can be defined side-by-side with rules you create or included separately as a custom baseline.</p> <p>Continue reading baseline reference.</p>"},{"location":"concepts/baselines/#baseline-groups","title":"Baseline groups","text":"<p> v2.9.0</p> <p>In addition to regular baselines, you can use a baseline group to provide a friendly name to an existing baseline. A baseline groups are set by configuring the Baseline.Group option.</p> <p>Experimental</p> <p>Baseline groups are a work in progress and subject to change. Currently, baseline groups allow only a single baseline to be referenced. Join or start a discussion to let us know how we can improve this feature going forward.</p> <p>Tip</p> <p>You can use baseline groups to reference a baseline. If a new baseline is made available in the future, update your baseline group in one place to start using the new baseline.</p> <p>In the following example, two baseline groups <code>latest</code> and <code>preview</code> are defined:</p> ps-rule.yaml<pre><code>baseline:\n  group:\n    latest: PSRule.Rules.Azure\\Azure.GA_2023_03\n    preview: PSRule.Rules.Azure\\Azure.Preview_2023_03\n</code></pre> <ul> <li>The <code>latest</code> baseline group is set to <code>Azure.GA_2023_03</code> within the <code>PSRule.Rules.Azure</code> module.</li> <li>The <code>preview</code> baseline group is set to <code>Azure.Preview_2023_03</code> within the <code>PSRule.Rules.Azure</code> module.</li> </ul> <p>To use the baseline group, prefix the group name with <code>@</code> when running PSRule. For example:</p> GitHub ActionsAzure PipelinesGeneric with PowerShell <pre><code>- name: Run PSRule\n  uses: microsoft/ps-rule@v2.9.0\n  with:\n    modules: 'PSRule.Rules.Azure'\n    baseline: '@latest'\n</code></pre> <pre><code>- task: ps-rule-assert@2\n  displayName: Run PSRule\n  inputs:\n    modules: 'PSRule.Rules.Azure'\n    baseline: '@latest'\n</code></pre> <pre><code>Assert-PSRule -InputPath '.' -Baseline '@latest' -Module PSRule.Rules.Azure -Format File;\n</code></pre>"},{"location":"concepts/grouping-rules/","title":"Grouping rules","text":"<p>Abstract</p> <p>Labels are additional metadata that can be used to classify rules. Together with tags they can be used to group or filter rules.</p>"},{"location":"concepts/grouping-rules/#using-labels","title":"Using labels","text":"<p>When defining a rule you can specify labels to classify or link rules using a framework or standard. A single rule can be can linked to multiple labels. For example:</p> <ul> <li>The Azure Well-Architected Framework (WAF) defines pillars such as Security and Reliability.</li> <li>The CIS Benchmarks define a number of control IDs such as 3.12 and 13.4.</li> </ul> YAMLJSONPowerShell <p>To specify labels in YAML, use the <code>labels</code> property:</p> <pre><code>---\n# Synopsis: A rule with labels defined.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: WithLabels\n  labels:\n    Azure.WAF/pillar: Security\n    Azure.ASB.v3/control: [ 'ID-1', 'ID-2' ]\nspec: { }\n</code></pre> <p>To specify labels in JSON, use the <code>labels</code> property:</p> <pre><code>{\n  // Synopsis: A rule with labels defined.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"WithLabels\",\n    \"labels\": {\n      \"Azure.WAF/pillar\": \"Security\",\n      \"Azure.ASB.v3/control\": [ \"ID-1\", \"ID-2\" ]\n    }\n  },\n  \"spec\": { }\n}\n</code></pre> <p>To specify labels in PowerShell, use the <code>-Labels</code> parameter:</p> <pre><code># Synopsis: A rule with labels defined.\nRule 'WithLabels' -Labels @{ 'Azure.WAF/pillar' = 'Security'; 'Azure.ASB.v3/control' = @('ID-1', 'ID-2') } {\n    # Define conditions here\n} \n</code></pre>"},{"location":"concepts/grouping-rules/#filtering-with-labels","title":"Filtering with labels","text":"<p>A reason for assigning labels to rules is to perform filtering of rules to a specific subset. This can be accomplished using baselines and the <code>spec.rule.labels</code> property. For example:</p> <pre><code>---\n# Synopsis: A baseline which returns only security rules.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline6\nspec:\n  rule:\n    labels:\n      Azure.WAF/pillar: [ 'Security' ]\n\n---\n# Synopsis: A baseline which returns any rules that are classified to Azure.WAF/pillar.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline6\nspec:\n  rule:\n    labels:\n      Azure.WAF/pillar: '*'\n</code></pre>"},{"location":"concepts/lockfile/","title":"Lock file","text":"<p>Abstract</p> <p>PSRule v3 and later uses a lock file to define the modules and versions used to run analysis. This article describes the lock file and how to manage it.</p> <p>An optional lock file can be used to define the modules and versions used to run analysis. Using the lock file ensures that the same modules and versions are used across multiple machines, improving consistency.</p> <ul> <li>Lock file is present - PSRule will use the module versions defined in the lock file.</li> <li>Lock file is not present - PSRule will use the latest version of each module installed locally.</li> </ul> Name Supports lock file PowerShell No CLI Yes, v3 and later GitHub Actions Yes, v3 and later Azure Pipelines Yes, v3 task and later Visual Studio Code Yes, v3 and later <p>Important</p> <p>The lock file only applies to PSRule outside of PowerShell. When using PSRule as a PowerShell module, the lock file is ignored.</p>"},{"location":"concepts/lockfile/#restoring-modules","title":"Restoring modules","text":"<p>When the lock file is present, PSRule will restore the modules and versions defined in the lock file.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/","title":"Assertion methods","text":"<p>Describes the assertion helper that can be used within PSRule rule definitions.</p>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#description","title":"Description","text":"<p>PSRule includes an assertion helper exposed as a built-in variable <code>$Assert</code>. The <code>$Assert</code> object provides a consistent set of methods to evaluate objects.</p> <p>Each <code>$Assert</code> method returns an <code>AssertResult</code> object that contains the result of the assertion.</p> <p>The following built-in assertion methods are provided:</p> <ul> <li>APIVersion - The field value must be a date version string.</li> <li>Contains - The field value must contain at least one of the strings.</li> <li>Count - The field value must contain the specified number of items.</li> <li>EndsWith - The field value must match at least one suffix.</li> <li>FileHeader - The file must contain a comment header.</li> <li>FilePath - The file path must exist.</li> <li>Greater - The field value must be greater.</li> <li>GreaterOrEqual - The field value must be greater or equal to.</li> <li>HasDefaultValue - The object should not have the field or the field value is set to the default value.</li> <li>HasField - The object must have any of the specified fields.</li> <li>HasFields - The object must have all of the specified fields.</li> <li>HasFieldValue - The object must have the specified field and that field is not empty.</li> <li>HasJsonSchema - The object must reference a JSON schema with the <code>$schema</code> field.</li> <li>In - The field value must be included in the set.</li> <li>IsArray - The field value must be an array.</li> <li>IsBoolean - The field value must be a boolean.</li> <li>IsDateTime - The field value must be a DateTime.</li> <li>IsInteger - The field value must be an integer.</li> <li>IsLower - The field value must include only lowercase characters.</li> <li>IsNumeric - The field value must be a numeric type.</li> <li>IsString - The field value must be a string.</li> <li>IsUpper - The field value must include only uppercase characters.</li> <li>JsonSchema - The object must validate successfully against a JSON schema.</li> <li>Less - The field value must be less.</li> <li>LessOrEqual - The field value must be less or equal to.</li> <li>Like - The value must match any of the specified wildcard values.</li> <li>Match - The field value matches a regular expression pattern.</li> <li>NotContains - The value must not contain any of the specified strings.</li> <li>NotCount - The field value must not contain the specified number of items.</li> <li>NotEndsWith - The value must not end with any of the specified strings.</li> <li>NotHasField - The object must not have any of the specified fields.</li> <li>NotIn - The field value must not be included in the set.</li> <li>NotLike - The value must not match any of the specified wildcard values.</li> <li>NotMatch - The field value does not match a regular expression pattern.</li> <li>NotNull - The field value must not be null.</li> <li>NotStartsWith - The value must not start with any of the specified strings.</li> <li>NotWithinPath - The field must not be within the specified path.</li> <li>Null - The field value must not exist or be null.</li> <li>NullOrEmpty - The object must not have the specified field or it must be empty.</li> <li>TypeOf - The field value must be of the specified type.</li> <li>SetOf - The field value must match a set of specified values.</li> <li>StartsWith - The field value must match at least one prefix.</li> <li>Subset - The field value must include a set of specified values.</li> <li>Version - The field value must be a semantic version string.</li> <li>WithinPath - The field value must be within the specified path.</li> </ul> <p>The <code>$Assert</code> variable can only be used within a rule definition block or script pre-conditions.</p>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#using-assertion-methods","title":"Using assertion methods","text":"<p>An assertion method can be used like other methods in PowerShell. i.e. <code>$Assert.methodName(parameters)</code>.</p> <p>Assertion methods use the following standard pattern:</p> <ul> <li>The first parameter is always the input object of type <code>PSObject</code>, additional parameters can be included based on the functionality required by the method.<ul> <li>In many cases the input object will be <code>$TargetObject</code>, however assertion methods must not assume that <code>$TargetObject</code> will be used.</li> <li>Assertion methods must accept a <code>$Null</code> input object.</li> </ul> </li> <li>Assertion methods return the <code>AssertResult</code> object that is interpreted by the rule pipeline.</li> </ul> <p>Some assertion methods may overlap or provide similar functionality to built-in keywords. Where you have the choice, use built-in keywords. Use assertion methods for advanced cases or increased flexibility.</p> <p>In the following example, <code>Assert.HasFieldValue</code> asserts that <code>$TargetObject</code> should have a field named <code>Type</code> with a non-empty value.</p> <pre><code>Rule 'Assert.HasTypeField' {\n    $Assert.HasFieldValue($TargetObject, 'Type')\n}\n</code></pre> <p>To find perform multiple assertions use.</p> <pre><code>Rule 'Assert.HasRequiredFields' {\n    $Assert.HasFieldValue($TargetObject, 'Name')\n    $Assert.HasFieldValue($TargetObject, 'Type')\n    $Assert.HasFieldValue($TargetObject, 'Value')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#field-names","title":"Field names","text":"<p>Many of the built-in assertion methods accept an object path or field name. An object path is an expression that traverses object properties, keys or indexes of the input object. The syntax for an object path is inspired by JSONPath which is current an IETF Internet-Draft.</p> <p>The object path expression can contain:</p> <ul> <li>Property names for PSObjects or .NET objects.</li> <li>Keys for hash table or dictionaries.</li> <li>Indexes for arrays or collections.</li> <li>Queries that filter items from array or collection properties.</li> </ul> <p>For example:</p> <ul> <li><code>.</code>, or <code>$</code> refers to input object itself.</li> <li><code>Name</code>, <code>.Name</code>, or <code>$.Name</code> refers to the name member of the input object.</li> <li><code>Properties.enabled</code> refers to the enabled member under the Properties member.   Alternatively this can also be written as <code>Properties['enabled']</code>.</li> <li><code>Tags.env</code> refers to the env member under a hash table property of the input object.</li> <li><code>Tags+env</code> refers to the env member using a case-sensitive match.</li> <li><code>Properties.securityRules[0].name</code> references to the name member of the first security rule.</li> <li><code>Properties.securityRules[-1].name</code> references to the name member of the last security rule.</li> <li><code>Properties.securityRules[?@direction == 'Inbound'].name</code> returns the name of any inbound rules.   This will return an array of security rule names.</li> </ul> <p>Notable differences between object paths and JSONPath are:</p> <ul> <li>Member names (properties and keys) are case-insensitive by default.   To perform a case-sensitive match of a member name use a plus selector <code>+</code> in front of the member name.   Some assertions such as <code>HasField</code> provide an option to match case when matching member names.   When this is used, the plus selector perform an case-insensitive match.</li> <li>Quoted member names with single or double quotes are supported with dot selector.   i.e. <code>Properties.'spaced name'</code> is valid.</li> <li>Member names with a dash <code>-</code> are supported without being quoted.   However member names can not start or end with a dash.   i.e. <code>Properties.dashed-name</code> and <code>Properties.'-dashed-name'</code> are valid.</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#apiversion","title":"APIVersion","text":"<p>The <code>APIVersion</code> assertion method checks the field value is a valid date version. A constraint can optionally be provided to require the date version to be within a range.</p> <p>A date version uses the format <code>yyyy-MM-dd</code> (<code>2015-10-01</code>). Additionally an optional string prerelease identifier can be used <code>yyyy-MM-dd-prerelease</code> (<code>2015-10-01-preview.1</code>).</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>constraint</code> (optional) - A version constraint, see below for details of version constrain format.</li> <li><code>includePrerelease</code> (optional) - Determines if prerelease versions are included.   Unless specified this defaults to <code>$False</code>.</li> </ul> <p>The following are supported constraints:</p> <ul> <li><code>version</code> - Must match version exactly. This also accepts the prefix <code>=</code>.<ul> <li>e.g. <code>2015-10-01</code>, <code>=2015-10-01</code></li> </ul> </li> <li><code>&gt;version</code> - Must be greater than version.<ul> <li>e.g. <code>&gt;2015-10-01</code></li> </ul> </li> <li><code>&gt;=version</code> - Must be greater than or equal to version.<ul> <li>e.g. <code>&gt;=2015-10-01</code></li> </ul> </li> <li><code>&lt;version</code> - Must be less than version.<ul> <li>e.g. <code>&lt;2022-03-01</code></li> </ul> </li> <li><code>&lt;=version</code> - Must be less than or equal to version.<ul> <li>e.g. <code>&lt;=2022-03-01</code></li> </ul> </li> </ul> <p>An empty, null or <code>*</code> constraint matches all valid date versions.</p> <p>Multiple constraints can be joined together:</p> <ul> <li>Use a space to separate multiple constraints, each must be true (logical AND).</li> <li>Separates constraint sets with the double pipe <code>||</code>.   Only one constraint set must be true (logical OR).</li> </ul> <p>By example:</p> <ul> <li><code>2014-01-01 || &gt;=2015-10-01 &lt;2022-03-01</code> results in:<ul> <li>Pass: <code>2014-01-01</code>, <code>2015-10-01</code>, <code>2019-06-30</code>, <code>2022-02-01</code>.</li> <li>Fail: <code>2015-01-01</code>, <code>2022-09-01</code>.</li> </ul> </li> </ul> <p>Handling for prerelease versions:</p> <ul> <li>Constraints and versions containing prerelease identifiers are supported.   i.e. <code>&gt;=2015-10-01-preview</code> or <code>2015-10-01-preview</code>.</li> <li>A version containing a prerelease identifer follows similar ordering to semantic versioning.   i.e. <code>2015-10-01-preview</code> &lt; <code>2015-10-01-preview.1</code> &lt; <code>2015-10-01</code> &lt; <code>2022-03-01-preview</code> &lt; <code>2022-03-01</code>.</li> <li>A constraint without a prerelease identifer will only match a stable version by default.   Set <code>includePrerelease</code> to <code>$True</code> to include prerelease versions.   Alternatively use the <code>@pre</code> or <code>@prerelease</code> flag in a constraint.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a version string.</li> <li>The version '{0}' does not match the constraint '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'ValidAPIVersion' {\n    $Assert.APIVersion($TargetObject, 'apiVersion')\n}\n\nRule 'MinimumAPIVersion' {\n    $Assert.APIVersion($TargetObject, 'apiVersion', '&gt;=2015-10-01')\n}\n\nRule 'MinimumAPIVersionWithPrerelease' {\n    $Assert.APIVersion($TargetObject, 'apiVersion', '&gt;=2015-10-01-0', $True)\n}\n\nRule 'MinimumAPIVersionWithFlag' {\n    $Assert.APIVersion($TargetObject, 'apiVersion', '@pre &gt;=2015-10-01-0')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#contains","title":"Contains","text":"<p>The <code>Contains</code> assertion method checks the operand contains the specified string. If the operand is an array of strings, only one string must contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>text</code> - A string or an array of strings to compare the field value with. Only one string must match. When an empty array of strings is specified or text is an empty string, <code>Contains</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'text' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field '{0}' does not contain '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Contains' {\n    $Assert.Contains($TargetObject, 'ResourceGroupName', 'prod')\n    $Assert.Contains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#count","title":"Count","text":"<p>The <code>Count</code> assertion method checks the field value contains the specified number of items. The field value must be an array or collection.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>count</code> - The number of items that the field value must contain.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' has '{1}' items instead of '{2}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Count' {\n    $Assert.Count($TargetObject, 'items', 2)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#endswith","title":"EndsWith","text":"<p>The <code>EndsWith</code> assertion method checks the operand ends with the specified suffix. If the operand is an array of strings, only one string must end with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>suffix</code> - A suffix or an array of suffixes to compare the field value with. Only one suffix must match. When an empty array of suffixes is specified or suffix is an empty string, <code>EndsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'suffix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field '{0}' does not end with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'EndsWith' {\n    $Assert.EndsWith($TargetObject, 'ResourceGroupName', 'eus')\n    $Assert.EndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#fileheader","title":"FileHeader","text":"<p>The <code>FileHeader</code> assertion method checks a file for a comment header. When comparing the file header, the format of line comments are automatically detected by file extension. Single line comments are supported. Multi-line comments are not supported.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a valid file path.</li> <li><code>header</code> - One or more lines of a header to compare with file contents.</li> <li><code>prefix</code> (optional) - An optional comment prefix for each line. By default a comment prefix will automatically detected based on file extension. When set, detection by file extension is skipped.</li> </ul> <p>Prefix detection for line comments is supported with the following file extensions:</p> <ul> <li><code>.bicep</code>, <code>.bicepparam</code>, <code>.cs</code>, <code>.csx</code>, <code>.ts</code>, <code>.tsp</code>, <code>.tsx</code>, <code>.js</code>, <code>.jsx</code>, <code>.fs</code>, <code>.go</code>, <code>.groovy</code>, <code>.php</code>, <code>.cpp</code>, <code>.h</code>, <code>.java</code>, <code>.json</code>, <code>.jsonc</code>, <code>.scala</code>, <code>Jenkinsfile</code> - Use a prefix of (<code>//</code>).</li> <li><code>.editorconfig</code>, <code>.ipynb</code>, <code>.ps1</code>, <code>.psd1</code>, <code>.psm1</code>, <code>.yaml</code>, <code>.yml</code>, <code>.r</code>, <code>.py</code>, <code>.sh</code>, <code>.tf</code>, <code>.tfvars</code>, <code>.toml</code>, <code>.gitignore</code>, <code>.pl</code>, <code>.rb</code>, <code>Dockerfile</code> - Use a prefix of (<code>#</code>).</li> <li><code>.sql</code>, <code>.lau</code> - Use a prefix of (<code>--</code>).</li> <li><code>.bat</code>, <code>.cmd</code> - Use a prefix of (<code>::</code>).</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The file '{0}' does not exist.</li> <li>The header was not set.</li> </ul> <p>Examples:</p> <pre><code>Rule 'FileHeader' {\n    $Assert.FileHeader($TargetObject, 'FullName', @(\n        'Copyright (c) Microsoft Corporation.'\n        'Licensed under the MIT License.'\n    ));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#filepath","title":"FilePath","text":"<p>The <code>FilePath</code> assertion method checks the file exists. Checks use file system case-sensitivity rules.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a file path.</li> <li><code>suffix</code> (optional) - Additional file path suffixes to append. When specified each suffix is combined with the file path. Only one full file path must be a valid file for the assertion method to pass.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The file '{0}' does not exist.</li> </ul> <p>Examples:</p> <pre><code>Rule 'FilePath' {\n    $Assert.FilePath($TargetObject, 'FullName', @('CHANGELOG.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('LICENSE', 'LICENSE.txt'));\n    $Assert.FilePath($TargetObject, 'FullName', @('CODE_OF_CONDUCT.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('CONTRIBUTING.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('SECURITY.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('README.md'));\n    $Assert.FilePath($TargetObject, 'FullName', @('.github/CODEOWNERS'));\n    $Assert.FilePath($TargetObject, 'FullName', @('.github/PULL_REQUEST_TEMPLATE.md'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greater","title":"Greater","text":"<p>The <code>Greater</code> assertion method checks the field value is greater than the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &gt; '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Greater' {\n    $Assert.Greater($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greaterorequal","title":"GreaterOrEqual","text":"<p>The <code>GreaterOrEqual</code> assertion method checks the field value is greater or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &gt;= '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'GreaterOrEqual' {\n    $Assert.GreaterOrEqual($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasdefaultvalue","title":"HasDefaultValue","text":"<p>The <code>HasDefaultValue</code> assertion method check that the field does not exist or the field value is set to the default value.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>defaultValue</code> - The expected value if the field exists.</li> </ul> <p>This assertion will pass if:</p> <ul> <li>The field does not exist.</li> <li>The field value is set to <code>defaultValue</code>.</li> </ul> <p>This assertion will fail if:</p> <ul> <li>The field value is set to a value different from <code>defaultValue</code>.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' is set to '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasDefaultValue' {\n    $Assert.HasDefaultValue($TargetObject, 'Properties.osProfile.linuxConfiguration.provisionVMAgent', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfield","title":"HasField","text":"<p>The <code>HasField</code> assertion method checks the object has any of the specified fields.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, only one must exist.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field name.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>Does not exist.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasField' {\n    $Assert.HasField($TargetObject, 'Name')\n    $Assert.HasField($TargetObject, 'tag.Environment', $True)\n    $Assert.HasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfields","title":"HasFields","text":"<p>The <code>HasFields</code> assertion method checks the object has all of the specified fields.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified fields.</li> <li><code>field</code> - The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all fields must exist.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field name.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasFields' {\n    $Assert.HasFields($TargetObject, 'Name')\n    $Assert.HasFields($TargetObject, 'tag.Environment', $True)\n    $Assert.HasFields($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfieldvalue","title":"HasFieldValue","text":"<p>The <code>HasFieldValue</code> assertion method checks the field value of the object is not empty.</p> <p>A field value is empty if any of the following are true:</p> <ul> <li>The field does not exist.</li> <li>The field value is <code>$Null</code>.</li> <li>The field value is an empty array or collection.</li> <li>The field value is an empty string <code>''</code>.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>expectedValue</code> (optional) - Check that the field value is set to a specific value. To check <code>$Null</code> use <code>NullOrEmpty</code> instead. If <code>expectedValue</code> is <code>$Null</code> the field value will not be compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>Does not exist.</li> <li>Is null or empty.</li> <li>Is set to '{0}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasFieldValue' {\n    $Assert.HasFieldValue($TargetObject, 'Name')\n    $Assert.HasFieldValue($TargetObject, 'tag.Environment', 'production')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasjsonschema","title":"HasJsonSchema","text":"<p>The <code>HasJsonSchema</code> assertion method determines if the input object has a <code>$schema</code> property defined. If the <code>$schema</code> property is defined, it must not be empty and match one of the supplied schemas. If a trailing <code>#</code> is specified it is ignored from the <code>$schema</code> property and <code>uri</code> parameter below.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being compared.</li> <li><code>uri</code> - Optional. When specified, the object being compared must have a <code>$schema</code> property set to one of the specified schemas.</li> <li><code>ignoreScheme</code> - Optional. By default, <code>ignoreScheme</code> is <code>$False</code>. When <code>$True</code>, the schema will match if <code>http</code> or <code>https</code> is specified.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The field '$schema' does not exist.</li> <li>The field value '$schema' is not a string.</li> <li>The value of '$schema' is null or empty.</li> <li>None of the specified schemas match '{0}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'HasFieldValue' {\n    $Assert.HasJsonSchema($TargetObject)\n    $Assert.HasJsonSchema($TargetObject, \"http://json-schema.org/draft-07/schema`#\")\n    $Assert.HasJsonSchema($TargetObject, \"https://json-schema.org/draft-07/schema\", $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#jsonschema","title":"JsonSchema","text":"<p>The <code>JsonSchema</code> assertion method compares the input object against a defined JSON schema.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being compared against the JSON schema.</li> <li><code>uri</code> - A URL or file path to a JSON schema file formatted as UTF-8. Either a file path or URL can be used to specify the location of the schema file.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'uri' is null or empty.</li> <li>The JSON schema '{0}' could not be found.</li> <li>Failed schema validation on {0}. {1}</li> </ul> <p>Examples:</p> <pre><code>Rule 'JsonSchema' {\n    $Assert.JsonSchema($TargetObject, 'tests/PSRule.Tests/FromFile.Json.schema.json')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#in","title":"In","text":"<p>The <code>In</code> assertion method checks the field value is included in a set of values. The field value can either be an integer, float, array, or string. When the field value is an array, only one item must be included in the set.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>values</code> - An array of values that the field value is compared against.   When an empty array is specified, <code>In</code> will always fail.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value.   Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' was not included in the set.</li> </ul> <p>Examples:</p> <pre><code>Rule 'In' {\n    $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'))\n    $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isarray","title":"IsArray","text":"<p>The <code>IsArray</code> assertion method checks the field value is an array type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The field value '{1}' of type {0} is not [array].</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsArray' {\n    # Require Value1 to be an array\n    $Assert.IsArray($TargetObject, 'Value1')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isboolean","title":"IsBoolean","text":"<p>The <code>IsBoolean</code> assertion method checks the field value is a boolean type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not a boolean.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsBoolean' {\n    # Require Value1 to be a boolean\n    $Assert.IsBoolean($TargetObject, 'Value1')\n\n    # Require Value1 to be a boolean or a boolean string\n    $Assert.IsBoolean($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isdatetime","title":"IsDateTime","text":"<p>The <code>IsDateTime</code> assertion method checks the field value is a DateTime type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not a date.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsDateTime' {\n    # Require Value1 to be a DateTime\n    $Assert.IsDateTime($TargetObject, 'Value1')\n\n    # Require Value1 to be a DateTime or a DateTime string\n    $Assert.IsDateTime($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isinteger","title":"IsInteger","text":"<p>The <code>IsInteger</code> assertion method checks the field value is a integer type. The following types are considered integer types <code>int</code>, <code>long</code>, <code>byte</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not an integer.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsInteger' {\n    # Require Value1 to be an integer\n    $Assert.IsInteger($TargetObject, 'Value1')\n\n    # Require Value1 to be an integer or a integer string\n    $Assert.IsInteger($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#islower","title":"IsLower","text":"<p>The <code>IsLower</code> assertion method checks the field value uses only lowercase characters. Non-letter characters are ignored by default and will pass.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>requireLetters</code> (optional) - Require each character to be lowercase letters only. Non-letter characters are ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The value '{0}' does not contain only lowercase characters.</li> <li>The value '{0}' does not contain only letters.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsLower' {\n    # Require Name to be lowercase\n    $Assert.IsLower($TargetObject, 'Name')\n\n    # Require Name to only contain lowercase letters\n    $Assert.IsLower($TargetObject, 'Name', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isnumeric","title":"IsNumeric","text":"<p>The <code>IsNumeric</code> assertion method checks the field value is a numeric type. The following types are considered numeric types <code>int</code>, <code>long</code>, <code>float</code>, <code>byte</code>, <code>double</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>convert</code> (optional) - Try to convert numerical strings. By default strings are not converted.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not numeric.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsNumeric' {\n    # Require Value1 to be numeric\n    $Assert.IsNumeric($TargetObject, 'Value1')\n\n    # Require Value1 to be numeric or a numerical string\n    $Assert.IsNumeric($TargetObject, 'Value1', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isstring","title":"IsString","text":"<p>The <code>IsString</code> assertion method checks the field value is a string type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The value '{0}' is not a string.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsString' {\n    # Require Value1 to be a string\n    $Assert.IsString($TargetObject, 'Value1')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isupper","title":"IsUpper","text":"<p>The <code>IsUpper</code> assertion method checks the field value uses only uppercase characters. Non-letter characters are ignored by default and will pass.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>requireLetters</code> (optional) - Require each character to be uppercase letters only. Non-letter characters are ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The value '{0}' does not contain only uppercase characters.</li> <li>The value '{0}' does not contain only letters.</li> </ul> <p>Examples:</p> <pre><code>Rule 'IsUpper' {\n    # Require Name to be uppercase\n    $Assert.IsUpper($TargetObject, 'Name')\n\n    # Require Name to only contain uppercase letters\n    $Assert.IsUpper($TargetObject, 'Name', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#less","title":"Less","text":"<p>The <code>Less</code> assertion method checks the field value is less than the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &lt; '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Less' {\n    $Assert.Less($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#lessorequal","title":"LessOrEqual","text":"<p>The <code>LessOrEqual</code> assertion method checks the field value is less or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>value</code> - A integer to compare the field value against.</li> <li><code>convert</code> (optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' was not &lt;= '{1}'.</li> <li>The field value '{0}' can not be compared with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'LessOrEqual' {\n    $Assert.LessOrEqual($TargetObject, 'value', 3)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#like","title":"Like","text":"<p>The <code>Like</code> assertion method checks the field value matches a specified pattern. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A pattern or an array of patterns to compare the field value with. Only one pattern must match. When an empty array of patterns is specified, <code>Like</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The value '{0}' is not like '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Like' {\n    $Assert.Like($TargetObject, 'ResourceGroupName', 'rg-*')\n    $Assert.Like($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#match","title":"Match","text":"<p>The <code>Match</code> assertion method checks the field value matches a regular expression pattern.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A regular expression pattern to match.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field value '{0}' does not match the pattern '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Match' {\n    $Assert.Match($TargetObject, 'value', '^[a-z]*$')\n    $Assert.Match($TargetObject, 'value', '^[a-z]*$', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcontains","title":"NotContains","text":"<p>The <code>NotContains</code> assertion method checks the operand contains the specified string. This condition fails when any of the specified sub-strings are found. If the operand is an array of strings, this condition fails if any of the strings contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>text</code> - A string or an array of strings to compare the field value with. When an empty array of strings is specified or text is an empty string, <code>NotContains</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'text' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' contains '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotContains' {\n    $Assert.NotContains($TargetObject, 'ResourceGroupName', 'prod')\n    $Assert.NotContains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcount","title":"NotCount","text":"<p>The <code>NotCount</code> assertion method checks the field value does not contain the specified number of items. The field value must be an array or collection.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>count</code> - The number of items that the field value must contain.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' has '{1}' items instead of '{2}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotCount' {\n    $Assert.NotCount($TargetObject, 'items', 2)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notendswith","title":"NotEndsWith","text":"<p>The <code>NotEndsWith</code> assertion method checks the operand ends with the specified suffix. This condition fails when any of the specified sub-strings are found at the end of the operand. If the operand is an array of strings, this condition fails if any of the strings ends with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>suffix</code> - A suffix or an array of suffixes to compare the field value with. When an empty array of suffixes is specified or suffix is an empty string, <code>NotEndsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'suffix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' ends with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotEndsWith' {\n    $Assert.NotEndsWith($TargetObject, 'ResourceGroupName', 'eus')\n    $Assert.NotEndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nothasfield","title":"NotHasField","text":"<p>The <code>NotHasField</code> assertion method checks the object does not have any of the specified fields.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all must not exist.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field name.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' exists.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotHasField' {\n    $Assert.NotHasField($TargetObject, 'Name')\n    $Assert.NotHasField($TargetObject, 'tag.Environment', $True)\n    $Assert.NotHasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notin","title":"NotIn","text":"<p>The <code>NotIn</code> assertion method checks the field value is not in a set of values. The field value can either be an integer, array, float, or string. When the field value is an array, none of the items must be included in the set. If the field does not exist at all, it is not in the set and passes. To check the field exists combine this assertion method with <code>HasFieldValue</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>values</code> - An array values that the field value is compared against. When an empty array is specified, <code>NotIn</code> will always pass.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field value '{0}' was in the set.</li> </ul> <p>Examples:</p> <pre><code>Rule 'In' {\n    $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'))\n    $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notlike","title":"NotLike","text":"<p>The <code>NotLike</code> assertion method checks the field value matches a specified pattern. This condition fails when any of the specified patterns match the field value. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A pattern or an array of patterns to compare the field value with. When an empty array of pattens is specified, <code>NotLike</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' is like '{1}'</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotLike' {\n    $Assert.NotLike($TargetObject, 'ResourceGroupName', 'rg-*')\n    $Assert.NotLike($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notmatch","title":"NotMatch","text":"<p>The <code>NotMatch</code> assertion method checks the field value does not match a regular expression pattern. If the field does not exist at all, it does not match and passes. To check the field exists combine this assertion method with <code>HasFieldValue</code>.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>pattern</code> - A regular expression pattern to match.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field value '{0}' is not a string.</li> <li>The field value '{0}' matches the pattern '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotMatch' {\n    $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$')\n    $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$', $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notnull","title":"NotNull","text":"<p>The <code>NotNull</code> assertion method checks the field value of the object is not null.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotNull' {\n    $Assert.NotNull($TargetObject, 'Name')\n    $Assert.NotNull($TargetObject, 'tag.Environment')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notstartswith","title":"NotStartsWith","text":"<p>The <code>NotStartsWith</code> assertion method checks the operand starts with the specified prefix. This condition fails when any of the specified sub-strings are found at the start of the operand. If the operand is an array of strings, this condition fails if any of the strings start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>prefix</code> - A prefix or an array of prefixes to compare the field value with. When an empty array of prefixes is specified or prefix is an empty string, <code>NotStartsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The value '{0}' starts with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotStartsWith' {\n    $Assert.NotStartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n    $Assert.NotStartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notwithinpath","title":"NotWithinPath","text":"<p>The <code>NotWithinPath</code> assertion method checks the file is not within a specified path. Checks use file system case-sensitivity rules by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a file path. When the field is <code>InputFileInfo</code> or <code>FileInfo</code>, PSRule will automatically resolve the file path.</li> <li><code>path</code> - An array of one or more directory paths to check. Only one path must match.</li> <li><code>caseSensitive</code> (optional) - Determines if case-sensitive path matching is used. This can be set to <code>$True</code> or <code>$False</code>. When not set or <code>$Null</code>, the case-sensitivity rules of the working path file system will be used.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'path' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The file '{0}' is within the path '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NotWithinPath' {\n    # The file must not be within either policy/ or security/ sub-directories.\n    $Assert.NotWithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#null","title":"Null","text":"<p>The <code>Null</code> assertion method checks the field value of the object is null.</p> <p>A field value is null if any of the following are true:</p> <ul> <li>The field does not exist.</li> <li>The field value is <code>$Null</code>.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field value '{0}' is not null.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Null' {\n    $Assert.Null($TargetObject, 'NotField')\n    $Assert.Null($TargetObject, 'tag.NullField')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nullorempty","title":"NullOrEmpty","text":"<p>The <code>NullOrEmpty</code> assertion method checks the field value of the object is null or empty.</p> <p>A field value is null or empty if any of the following are true:</p> <ul> <li>The field does not exist.</li> <li>The field value is <code>$Null</code>.</li> <li>The field value is an empty array or collection.</li> <li>The field value is an empty string <code>''</code>.</li> </ul> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' is not empty.</li> </ul> <p>Examples:</p> <pre><code>Rule 'NullOrEmpty' {\n    $Assert.NullOrEmpty($TargetObject, 'Name')\n    $Assert.NullOrEmpty($TargetObject, 'tag.Environment')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#typeof","title":"TypeOf","text":"<p>The <code>TypeOf</code> assertion method checks the field value is a specified type.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>type</code> - One or more specified types to check. The field value only has to match a single type of more than one type is specified.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'type' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is null.</li> <li>The field value '{2}' of type {1} is not {0}.</li> </ul> <p>Examples:</p> <pre><code>Rule 'TypeOf' {\n    # Require Value1 to be [int]\n    $Assert.TypeOf($TargetObject, 'Value1', [int])\n\n    # Require Value1 to be [int] or [long]\n    $Assert.TypeOf($TargetObject, 'Value1', @([int], [long]))\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#setof","title":"SetOf","text":"<p>The <code>SetOf</code> assertion method checks the field value only includes all of the specified values. The field value must be an array or collection. Specified values can be included in the field value in any order.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>values</code> - An array of values that the field value is compared against.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value.   Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' did not contain '{1}'.</li> <li>The field '{0}' has '{1}' items instead of '{2}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Subset' {\n    $Assert.SetOf($TargetObject, 'zones', @('1', '2', '3'))\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#startswith","title":"StartsWith","text":"<p>The <code>StartsWith</code> assertion method checks the operand starts with the specified prefix. If the operand is an array of strings, only one string must start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>prefix</code> - A prefix or an array of prefixes to compare the field value with. Only one prefix must match. When an empty array of prefixes is specified or prefix is an empty string, <code>StartsWith</code> always passes.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value. Case is ignored by default.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'prefix' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a string.</li> <li>The field '{0}' does not start with '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'StartsWith' {\n    $Assert.StartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n    $Assert.StartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#subset","title":"Subset","text":"<p>The <code>Subset</code> assertion method checks the field value includes all of the specified values. The field value may also contain additional values that are not specified in the <code>values</code> parameter. The field value must be an array or collection. Specified values can be included in the field value in any order.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check.   This is a case insensitive compare.</li> <li><code>values</code> - An array of values that the field value is compared against.   When an empty array is specified, <code>Subset</code> will always pass.</li> <li><code>caseSensitive</code> (optional) - Use a case sensitive compare of the field value.   Case is ignored by default.</li> <li><code>unique</code> (optional) - A boolean value that indicates if the items must be unique.   When <code>true</code> the field value must not contain duplicate items.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'values' is null.</li> <li>The field '{0}' does not exist.</li> <li>The field '{0}' is not enumerable.</li> <li>The field '{0}' did not contain '{1}'.</li> <li>The field '{0}' included multiple instances of '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'Subset' {\n    $Assert.Subset($TargetObject, 'logs', @('cluster-autoscaler', 'kube-apiserver', 'kube-scheduler'), $True, $True)\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#version","title":"Version","text":"<p>The <code>Version</code> assertion method checks the field value is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field to check. This is a case insensitive compare.</li> <li><code>constraint</code> (optional) - A version constraint, see below for details of version constrain format.</li> <li><code>includePrerelease</code> (optional) - Determines if prerelease versions are included. Unless specified this defaults to <code>$False</code>.</li> </ul> <p>The following are supported constraints:</p> <ul> <li><code>version</code> - Must match version exactly. This also accepts the following prefixes; <code>=</code>, <code>v</code>, <code>V</code>.<ul> <li>e.g. <code>1.2.3</code>, <code>=1.2.3</code></li> </ul> </li> <li><code>&gt;version</code> - Must be greater than version.<ul> <li>e.g. <code>&gt;1.2.3</code></li> </ul> </li> <li><code>&gt;=version</code> - Must be greater than or equal to version.<ul> <li>e.g. <code>&gt;=1.2.3</code></li> </ul> </li> <li><code>&lt;version</code> - Must be less than version.<ul> <li>e.g. <code>&lt;1.2.3</code></li> </ul> </li> <li><code>&lt;=version</code> - Must be less than or equal to version.<ul> <li>e.g. <code>&lt;=1.2.3</code></li> </ul> </li> <li><code>^version</code> - Compatible with version.<ul> <li>e.g. <code>^1.2.3</code> - <code>&gt;=1.2.3</code>, <code>&lt;2.0.0</code></li> </ul> </li> <li><code>~version</code> - Approximately equivalent to version<ul> <li>e.g. <code>~1.2.3</code> - <code>&gt;=1.2.3</code>, <code>&lt;1.3.0</code></li> </ul> </li> </ul> <p>An empty, null or <code>*</code> constraint matches all valid semantic versions.</p> <p>Multiple constraints can be joined together:</p> <ul> <li>Use a space to separate multiple constraints, each must be true (logical AND).</li> <li>Separates constraint sets with the double pipe <code>||</code>. Only one constraint set must be true (logical OR).</li> </ul> <p>By example:</p> <ul> <li><code>1.2.3 || &gt;=3.4.5 &lt;5.0.0</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>3.4.5</code>, <code>3.5.0</code>, <code>4.9.9</code>.</li> <li>Fail: <code>3.0.0</code>, <code>5.0.0</code>.</li> </ul> </li> </ul> <p>Handling for prerelease versions:</p> <ul> <li>Constraints and versions containing prerelease identifiers are supported. i.e. <code>&gt;=1.2.3-build.1</code> or <code>1.2.3-build.1</code>.</li> <li>A version containing a prerelease identifer follows semantic versioning rules. i.e. <code>1.2.3-alpha</code> &lt; <code>1.2.3-alpha.1</code> &lt; <code>1.2.3-alpha.beta</code> &lt; <code>1.2.3-beta</code> &lt; <code>1.2.3-beta.2</code> &lt; <code>1.2.3-beta.11</code> &lt; <code>1.2.3-rc.1</code> &lt; <code>1.2.3</code>.</li> <li>A constraint without a prerelease identifer will only match a stable version by default. Set <code>includePrerelease</code> to <code>$True</code> to include prerelease versions.</li> <li>Constraints with a prerelease identifer will only match:<ul> <li>Matching prerelease versions of the same major.minor.patch version by default. Set <code>includePrerelease</code> to <code>$True</code> to include prerelease versions of all matching versions. Alternatively use the <code>@pre</code> or <code>@prerelease</code> flag in a constraint.</li> <li>Matching stable versions.</li> </ul> </li> </ul> <p>By example:</p> <ul> <li><code>&gt;=1.2.3</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>9.9.9</code>.</li> <li>Fail: <code>1.2.3-build.1</code>, <code>9.9.9-build.1</code>.</li> </ul> </li> <li><code>&gt;=1.2.3-0</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>1.2.3-build.1</code>, <code>9.9.9</code>.</li> <li>Fail: <code>9.9.9-build.1</code>.</li> </ul> </li> <li><code>&lt;1.2.3</code> results in:<ul> <li>Pass: <code>1.2.2</code>, <code>1.0.0</code>.</li> <li>Fail: <code>1.0.0-build.1</code>, <code>1.2.3-build.1</code>.</li> </ul> </li> <li><code>&lt;1.2.3-0</code> results in:<ul> <li>Pass: <code>1.2.2</code>, <code>1.0.0</code>.</li> <li>Fail: <code>1.0.0-build.1</code>, <code>1.2.3-build.1</code>.</li> </ul> </li> <li><code>@pre &gt;=1.2.3</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>9.9.9</code>, <code>9.9.9-build.1</code></li> <li>Fail: <code>1.2.3-build.1</code>.</li> </ul> </li> <li><code>@pre &gt;=1.2.3-0</code> results in:<ul> <li>Pass: <code>1.2.3</code>, <code>1.2.3-build.1</code>, <code>9.9.9</code>, <code>9.9.9-build.1</code>.</li> </ul> </li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The field value '{0}' is not a version string.</li> <li>The version '{0}' does not match the constraint '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'ValidVersion' {\n    $Assert.Version($TargetObject, 'version')\n}\n\nRule 'MinimumVersion' {\n    $Assert.Version($TargetObject, 'version', '&gt;=1.2.3')\n}\n\nRule 'MinimumVersionWithPrerelease' {\n    $Assert.Version($TargetObject, 'version', '&gt;=1.2.3-0', $True)\n}\n\nRule 'MinimumVersionWithFlag' {\n    $Assert.Version($TargetObject, 'version', '@pre &gt;=1.2.3-0')\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#withinpath","title":"WithinPath","text":"<p>The <code>WithinPath</code> assertion method checks if the file path is within a required path. Checks use file system case-sensitivity rules by default.</p> <p>The following parameters are accepted:</p> <ul> <li><code>inputObject</code> - The object being checked for the specified field.</li> <li><code>field</code> - The name of the field containing a file path. When the field is <code>InputFileInfo</code> or <code>FileInfo</code>, PSRule will automatically resolve the file path.</li> <li><code>path</code> - An array of one or more directory paths to check. Only one path must match.</li> <li><code>caseSensitive</code> (optional) - Determines if case-sensitive path matching is used. This can be set to <code>$True</code> or <code>$False</code>. When not set or <code>$Null</code>, the case-sensitivity rules of the working path file system will be used.</li> </ul> <p>Reasons include:</p> <ul> <li>The parameter 'inputObject' is null.</li> <li>The parameter 'field' is null or empty.</li> <li>The parameter 'path' is null or empty.</li> <li>The field '{0}' does not exist.</li> <li>The file '{0}' is not within the path '{1}'.</li> </ul> <p>Examples:</p> <pre><code>Rule 'WithinPath' {\n    # Require the file to be within either policy/ or security/ sub-directories.\n    $Assert.WithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#advanced-usage","title":"Advanced usage","text":"<p>The <code>AssertResult</code> object returned from assertion methods:</p> <ul> <li>Handles pass/ fail conditions and collection of reason information.</li> <li>Allows rules to implement their own handling or forward it up the stack to affect the rule outcome.</li> </ul> <p>The following properties are available:</p> <ul> <li><code>Result</code> - Either <code>$True</code> (Pass) or <code>$False</code> (Fail).</li> </ul> <p>The following methods are available:</p> <ul> <li><code>AddReason(&lt;string&gt; text)</code> - Can be used to append additional reasons to the result.   A reason can only be set if the assertion failed.   Reason text should be localized before calling this method.   Localization can be done using the <code>$LocalizedData</code> automatic variable.</li> <li><code>WithReason(&lt;string&gt; text, &lt;bool&gt; replace)</code> - Can be used to append or replace reasons on the result.   In addition, <code>WithReason</code> can be chained.</li> <li><code>Reason(&lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason on the results with a formatted string.   This method can be chained.   For usage see examples below.</li> <li><code>ReasonFrom(&lt;string&gt; path, &lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason on the results with a formatted string.   Path specifies the object path that affected the reason.   This method can be chained.   For usage see examples below.</li> <li><code>ReasonIf(&lt;bool&gt; condition, &lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason if the condition is true.   This method can be chained, similar to <code>Reason</code>.</li> <li><code>ReasonIf(&lt;string&gt; path, &lt;bool&gt; condition, &lt;string&gt; text, params &lt;object[]&gt; args)</code> - Replaces the reason if the condition is true.   This method can be chained, similar to <code>ReasonFrom</code>.</li> <li><code>PathPrefix(&lt;string&gt; path)</code> - Adds a path prefix to any reasons.   This method can be chained.   For usage see examples below.</li> <li><code>GetReason()</code> - Gets any reasons currently associated with the failed result.</li> <li><code>Complete()</code> - Returns <code>$True</code> (Pass) or <code>$False</code> (Fail) to the rule record.   If the assertion failed, any reasons are automatically added to the rule record.   To read the result without adding reason to the rule record use the <code>Result</code> property.</li> <li><code>Ignore()</code> - Ignores the result. Nothing future is returned and any reasons are cleared.   Use this method when implementing custom handling.</li> </ul> <p>Use of <code>Complete</code> is optional, uncompleted results are automatically completed after the rule has executed. Uncompleted results may return reasons out of sequence.</p> <p>Using these advanced methods is not supported in rule script pre-conditions.</p> <p>In this example, <code>Complete</code> is used to find the first field with an empty value.</p> <pre><code>Rule 'Assert.HasFieldValue' {\n    $Assert.HasFieldValue($TargetObject, 'Name').Complete() -and\n        $Assert.HasFieldValue($TargetObject, 'Type').Complete() -and\n        $Assert.HasFieldValue($TargetObject, 'Value').Complete()\n}\n</code></pre> <p>In this example, the built-in reason is replaced with a custom reason, and immediately returned. The reason text is automatically formatted with any parameters provided.</p> <pre><code>Rule 'Assert.HasCustomValue' {\n    $Assert.\n        HasDefaultValue($TargetObject, 'value', 'test').\n        Reason('The field {0} is using a non-default value: {1}', 'value', $TargetObject.value)\n\n    # With localized string\n    $Assert.\n        HasDefaultValue($TargetObject, 'value', 'test').\n        Reason($LocalizedData.NonDefaultValue, 'value', $TargetObject.value)\n}\n</code></pre> <p>In this example, the built-in reason has a path prefix added to any reasons.</p> <pre><code>Rule 'Assert.ChildHasFieldValue' {\n    $items = @($TargetObject.items)\n    for ($i = 0; $i -lt $items.Length; $i++) {\n        $Assert.HasFieldValue($items[$i], 'Name').PathPrefix(\"items[$i]\")\n    }\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#downstream-issues","title":"Downstream issues","text":"<p>Before PSRule performs analysis external tools or rules modules may have already performed analysis. Issues identified by downstream tools can be consumed by PSRule using the <code>_PSRule.issue</code> property. If a <code>_PSRule</code> property exists with <code>issue</code> sub-property PSRule will consume <code>issue</code> as an array of issues.</p> <p>Each issue has the following properties:</p> <ul> <li><code>type</code> - The issue type.   Issues are filtered by type.</li> <li><code>name</code> - The name of a specific issue.</li> <li><code>message</code> - The reason message for the issue.</li> </ul> <p>To get issues for an object use the <code>Get</code> or <code>Any</code> methods.</p> <pre><code># Get an array of all issues for the current object.\n$PSRule.Issue.Get();\n\n# Get an array of issues of a specific type.\n$PSRule.Issue.Get('CustomIssue');\n\n# Return true of any issues exist.\n$PSRule.Issue.Any();\n\n# Return true of any issues of a specific type exist.\n$PSRule.Issue.Any('CustomIssue');\n</code></pre> <p>For example:</p> <pre><code># Synopsis: Fail if the object has any 'PSRule.Rules.Azure.Parameter.Insecure' issues.\nRule 'IssueReportTest' {\n    $Assert.Create($PSRule.Issue.Get('PSRule.Rules.Azure.Parameter.Insecure'));\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#authoring-assertion-methods","title":"Authoring assertion methods","text":"<p>The following built-in helper methods are provided for working with <code>$Assert</code> when authoring new assertion methods:</p> <ul> <li><code>Create(&lt;bool&gt; condition, &lt;string&gt; reason, params &lt;object[]&gt; args)</code> - Returns a result either pass or fail assertion result.   Additional arguments can be provided to format the custom reason string.</li> <li><code>Create(&lt;TargetIssueInfo[]&gt;)</code> - Returns a result based on reported downstream issues.</li> <li><code>Pass()</code> - Returns a pass assertion result.</li> <li><code>Fail()</code> - Results a fail assertion result.</li> <li><code>Fail(&lt;string&gt; reason, params &lt;object[]&gt; args)</code> - Results a fail assertion result with a custom reason.   Additional arguments can be provided to format the custom reason string.</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#aggregating-assertion-methods","title":"Aggregating assertion methods","text":"<p>The following built-in helper methods are provided for aggregating assertion results:</p> <ul> <li><code>AnyOf(&lt;AssertResult[]&gt; results)</code> - Results from assertion methods are aggregated into a single result.   If any result is a pass, the result is a pass.   If all results are fails, the result is a fail and any reasons are added to the result.   If no results are provided, the result is a fail.</li> <li><code>AllOf(&lt;AssertResult[]&gt; results)</code> - Results from assertion methods are aggregated into a single result.   If all results are passes, the result is a pass.   If any result is a fail, the result is a fail and any reasons are added to the result.   If no results are provided, the result is a fail.</li> </ul> <p>For example:</p> <pre><code>Rule 'Assert.HasFieldValue' {\n    $Assert.AllOf(\n        $Assert.HasFieldValue($TargetObject, 'Name'),\n        $Assert.HasFieldValue($TargetObject, 'Type'),\n        $Assert.HasFieldValue($TargetObject, 'Value')\n    )\n}\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#links","title":"Links","text":"<ul> <li>about_PSRule_Variables</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/","title":"Badges","text":"<p>Describes using the badge API with PSRule.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. The badge API can be used to create badges within a convention.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-the-api","title":"Using the API","text":"<p>PSRule provides the <code>$PSRule</code> built-in variable that exposes the badge API. By using the <code>$PSRule.Badges.Create</code> method you can create a standard or custom badge.</p> <p>The create method provides the following overloads:</p> <pre><code>// Create a badge for the worst case of an analyzed object.\nIBadge Create(InvokeResult result);\n\n// Create a badge for the worst case of all analyzed objects.\nIBadge Create(IEnumerable&lt;InvokeResult&gt; result);\n\n// Create a custom badge.\nIBadge Create(string title, BadgeType type, string label);\n</code></pre> <p>A badge once created can be read as a string or written to disk with the following methods:</p> <pre><code>// Get the badge as SVG text content.\nstring ToSvg();\n\n// Write the SVG badge content directly to disk.\nvoid ToFile(string path);\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#defining-conventions","title":"Defining conventions","text":"<p>To define a convention, add a <code>Export-PSRuleConvention</code> block within a <code>.Rule.ps1</code> file. The <code>.Rule.ps1</code> must be in an included path or module with <code>-Path</code> or <code>-Module</code>.</p> <p>The <code>Export-PSRuleConvention</code> block works similar to the <code>Rule</code> block. Each convention must have a unique name. Currently the badge API support creating badges in the <code>-End</code> block.</p> <p>For example:</p> <pre><code># Synopsis: A convention that generates a badge for an aggregate result.\nExport-PSRuleConvention 'Local.Aggregate' -End {\n    $PSRule.Badges.Create($PSRule.Output).ToFile('out/badges/aggregate.svg');\n}\n</code></pre> <pre><code># Synopsis: A convention that generates a custom badge.\nExport-PSRuleConvention 'Local.CustomBadge' -End {\n    $PSRule.Badges.Create('PSRule', [PSRule.Badges.BadgeType]::Success, 'OK').ToFile('out/badges/custom.svg');\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-conventions","title":"Using conventions","text":"<p>A convention can be included by using the <code>-Convention</code> parameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:</p> <pre><code>Invoke-PSRule -Convention 'Local.Aggregate';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/","title":"Baselines","text":"<p>Describes usage of baselines within PSRule.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#description","title":"Description","text":"<p>PSRule lets you define a baseline. A baseline includes a set of rule and configuration options that are used for evaluating objects.</p> <p>The following baseline options can be configured:</p> <ul> <li>Binding.Field</li> <li>Binding.IgnoreCase</li> <li>Binding.NameSeparator</li> <li>Binding.PreferTargetInfo</li> <li>Binding.TargetName</li> <li>Binding.TargetType</li> <li>Binding.UseQualifiedName</li> <li>Configuration</li> <li>Rule.Include</li> <li>Rule.IncludeLocal</li> <li>Rule.Exclude</li> <li>Rule.Tag</li> </ul> <p>Baseline options can be:</p> <ul> <li>Included as a baseline spec within a YAML or JSON file.<ul> <li>When using this method, multiple baseline specs can be defined within the same YAML/JSON file.</li> <li>Each YAML baseline spec is separated using <code>---</code>.</li> <li>Each JSON baseline spec is separated by JSON objects in a JSON array.</li> </ul> </li> <li>Set within a workspace options file like <code>ps-rule.yaml</code> or <code>ps-rule.json</code>.<ul> <li>Only a single baseline can be specified.</li> <li>See about_PSRule_Options for details on using this method.</li> </ul> </li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#baseline-specs","title":"Baseline specs","text":"<p>YAML baseline specs are saved within a YAML file with a <code>.Rule.yaml</code> or <code>.Rule.yml</code> extension, for example <code>Baseline.Rule.yaml</code>.</p> <p>JSON baseline specs are saved within a file with a <code>.Rule.json</code> or <code>.Rule.jsonc</code> extension, for example <code>Baseline.Rule.json</code>. Use <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>To define a YAML baseline spec use the following structure:</p> <pre><code>---\n# Synopsis: &lt;synopsis&gt;\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: &lt;name&gt;\n  annotations: { }\nspec:\n  # One or more baseline options\n  binding: { }\n  rule: { }\n  configuration: { }\n</code></pre> <p>For example:</p> <pre><code>---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: Baseline1\nspec:\n  binding:\n    field:\n      id:\n      - ResourceId\n    targetName:\n    - Name\n    - ResourceName\n    - ResourceGroupName\n    targetType:\n    - ResourceType\n  rule:\n    include:\n    - Rule1\n    - Rule2\n  configuration:\n    allowedLocations:\n    - 'Australia East'\n    - 'Australia South East'\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: Baseline2\nspec:\n  binding:\n    targetName:\n    - Name\n    - ResourceName\n    - ResourceGroupName\n    targetType:\n    - ResourceType\n  rule:\n    include:\n    - Rule1\n    - Rule3\n  configuration:\n    allowedLocations:\n    - 'Australia East'\n</code></pre> <p>To define a JSON baseline spec use the following structure:</p> <pre><code>[\n  {\n    // Synopsis: &lt;synopsis&gt;\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"&lt;name&gt;\",\n      \"annotations\": {}\n    },\n    \"spec\": {\n      \"binding\": {},\n      \"rule\": {},\n      \"configuration\": {}\n    }\n  }\n]\n</code></pre> <p>For example:</p> <pre><code>[\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"Baseline1\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"field\": {\n          \"id\": [\n            \"ResourceId\"\n          ]\n        },\n        \"targetName\": [\n          \"Name\",\n          \"ResourceName\",\n          \"ResourceGroupName\"\n        ],\n        \"targetType\": [\n          \"ResourceType\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"Rule1\",\n          \"Rule2\"\n        ]\n      },\n      \"configuration\": {\n        \"allowedLocations\": [\n          \"Australia East\",\n          \"Australia South East\"\n        ]\n      }\n    }\n  },\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"Baseline2\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"targetName\": [\n          \"Name\",\n          \"ResourceName\",\n          \"ResourceGroupName\"\n        ],\n        \"targetType\": [\n          \"ResourceType\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"Rule1\",\n          \"Rule3\"\n        ]\n      },\n      \"configuration\": {\n        \"allowedLocations\": [\n          \"Australia East\"\n        ]\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#baseline-scopes","title":"Baseline scopes","text":"<p>When baseline options are set, PSRule uses the following order to determine precedence.</p> <ol> <li>Parameter - <code>-Name</code> and <code>-Tag</code>.</li> <li>Explicit - A named baseline specified with <code>-Baseline</code>.</li> <li>Workspace - Included in <code>ps-rule.yaml</code> or specified on the command line with <code>-Option</code>.</li> <li>Module - A baseline object included in a <code>.Rule.yaml</code> or <code>.Rule.json</code> file.</li> </ol> <p>After precedence is determined, baselines are merged and null values are ignored, such that:</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#annotations","title":"Annotations","text":"<p>Additional baseline annotations can be provided as key/ value pairs. Annotations can be used to provide additional information that is available in <code>Get-PSRuleBaseline</code> output.</p> <p>The following reserved annotation exists:</p> <ul> <li><code>obsolete</code> - Marks the baseline as obsolete when set to <code>true</code>. PSRule will generate a warning when an obsolete baseline is used.</li> </ul> <p>YAML example:</p> <pre><code>---\n# Synopsis: This is an example baseline that is obsolete\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: ObsoleteBaseline\n  annotations:\n    obsolete: true\nspec: { }\n</code></pre> <p>JSON example:</p> <pre><code>[\n  {\n    // Synopsis: This is an example baseline that is obsolete\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"ObsoleteBaseline\",\n      \"annotations\": {\n        \"obsolete\": true\n      }\n    },\n    \"spec\": {}\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselineruleyaml","title":"Example Baseline.Rule.yaml","text":"<pre><code># Example Baseline.Rule.yaml\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline1\nspec:\n  binding:\n    targetName:\n    - AlternateName\n    targetType:\n    - kind\n  rule:\n    include:\n    - 'WithBaseline'\n  configuration:\n    key1: value1\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n  name: TestBaseline2\nspec:\n  binding:\n    targetName:\n    - AlternateName\n    targetType:\n    - kind\n  rule:\n    include:\n    - 'WithBaseline'\n  configuration:\n    key1: value1\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselinerulejson","title":"Example Baseline.Rule.json","text":"<pre><code>// Example Baseline.Rule.json\n\n[\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"TestBaseline1\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"targetName\": [\n          \"AlternateName\"\n        ],\n        \"targetType\": [\n          \"kind\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"WithBaseline\"\n        ]\n      },\n      \"configuration\": {\n        \"key1\": \"value1\"\n      }\n    }\n  },\n  {\n    // Synopsis: This is an example baseline\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Baseline\",\n    \"metadata\": {\n      \"name\": \"TestBaseline2\"\n    },\n    \"spec\": {\n      \"binding\": {\n        \"targetName\": [\n          \"AlternateName\"\n        ],\n        \"targetType\": [\n          \"kind\"\n        ]\n      },\n      \"rule\": {\n        \"include\": [\n          \"WithBaseline\"\n        ]\n      },\n      \"configuration\": {\n        \"key1\": \"value1\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/","title":"Conventions","text":"<p>Describes PSRule Conventions including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. Each convention, hooks into one or more places within the pipeline.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-conventions","title":"Using conventions","text":"<p>A convention can be included by using the <code>-Convention</code> parameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:</p> <pre><code>Invoke-PSRule -Convention 'ExampleConvention';\n</code></pre> <p>If multiple conventions are specified in an array, all are executed in they are specified. As a result, the convention specified last may override state set by earlier conventions.</p> <pre><code>Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#defining-conventions","title":"Defining conventions","text":"<p>To define a convention, add a <code>Export-PSRuleConvention</code> block within a <code>.Rule.ps1</code> file. The <code>.Rule.ps1</code> must be in an included path or module with <code>-Path</code> or <code>-Module</code>.</p> <p>The <code>Export-PSRuleConvention</code> block works similar to the <code>Rule</code> block. Each convention must have a unique name. For example:</p> <pre><code># Synopsis: An example convention.\nExport-PSRuleConvention 'ExampleConvention' {\n    # Add code here\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#initialize-begin-process-end-blocks","title":"Initialize Begin Process End blocks","text":"<p>Conventions define four executable blocks <code>Initialize</code>, <code>Begin</code>, <code>Process</code>, <code>End</code> similar to a PowerShell function. Each block is injected in a different part of the pipeline as follows:</p> <ul> <li><code>Initialize</code> occurs once at the beginning of the pipeline.   Use <code>Initialize</code> to perform any initialization required by the convention.</li> <li><code>Begin</code> occurs once per object before the any rules are executed.   Use <code>Begin</code> blocks to perform expansion, set data, or alter the object before rules are processed.</li> <li><code>Process</code> occurs once per object after all rules are executed.   Use <code>Process</code> blocks to perform per object tasks such as generate badges.</li> <li><code>End</code> occurs only once after all objects have been processed.   Use <code>End</code> blocks to upload results to an external service.</li> </ul> <p>Convention block limitations:</p> <ul> <li><code>Initialize</code> can not use automatic variables except <code>$PSRule</code>.   Most methods and properties of <code>$PSRule</code> are not available in <code>Initialize</code>.</li> <li><code>Begin</code> and <code>Process</code> can not use rule specific variables such as <code>$Rule</code>.   These blocks are executed outside of the context of a single rule.</li> <li><code>End</code> can not use automatic variables except <code>$PSRule</code>.   Most methods and properties of <code>$PSRule</code> are not available in <code>End</code>.</li> </ul> <p>By default, the <code>Process</code> block used. For example:</p> <pre><code># Synopsis: The default { } executes the process block\nExport-PSRuleConvention 'ExampleConvention' {\n    # Process block\n}\n\n# Synopsis: With optional -Process parameter name\nExport-PSRuleConvention 'ExampleConvention' -Process {\n    # Process block\n}\n</code></pre> <p>To use <code>Initialize</code>, <code>Begin</code>, or <code>End</code> explicitly add these blocks. For example:</p> <pre><code>Export-PSRuleConvention 'ExampleConvention' -Process {\n    # Process block\n} -Begin {\n    # Begin block\n} -End {\n    # End block\n} -Initialize {\n    # Initialize block\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#including-with-options","title":"Including with options","text":"<p>Conventions can be included by name within options in addition to using the <code>-Convention</code> parameter. To specify a convention within YAML options use the following:</p> ps-rule.yaml<pre><code>convention:\n  include:\n  - 'ExampleConvention1'\n  - 'ExampleConvention2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-within-modules","title":"Using within modules","text":"<p>Conventions can be shipped within a module using the same packaging and distribution process as rules. Additionally, conventions shipped within a module can be automatically included. By default, PSRule does not include conventions shipped within a module. To use a convention included in a module use the <code>-Convention</code> parameter or options configuration.</p> <p>A module can automatically include a convention by specifying the convention by name in module configuration. For example:</p> Config.Rule.yaml<pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: ExampleModule\nspec:\n  convention:\n    include:\n    - 'ExampleConvention1'\n    - 'ExampleConvention2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#execution-order","title":"Execution order","text":"<p>Conventions are executed in the order they are specified. This is true for <code>Initialize</code>, <code>Begin</code>, <code>Process</code>, and <code>End</code> blocks. i.e. In the following example <code>ExampleConvention1</code> is execute before <code>ExampleConvention2</code>.</p> <pre><code>Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\n</code></pre> <p>When conventions are specified from multiple locations PSRule orders conventions as follows:</p> <ol> <li>Using <code>-Convention</code> parameter.</li> <li>PSRule options.</li> <li>Module configuration.</li> </ol>"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/","title":"Documentation","text":"<p>Describes usage of documentation within PSRule.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#description","title":"Description","text":"<p>PSRule includes a built-in documentation system that provide culture specific help and metadata for resources. Documentation is composed of markdown files that can be optionally shipped with a module.</p> <p>When markdown documentation is defined, this content will be used instead of inline synopsis comments. Markdown documentation is supported for rules and suppression groups.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#getting-documentation","title":"Getting documentation","text":"<p>To get documentation for a rule use the <code>Get-PSRuleHelp</code> cmdlet.</p> <p>For example:</p> <pre><code>Get-PSRuleHelp &lt;rule-name&gt;\n</code></pre> <p>Each rule can include the following documentation:</p> <ul> <li>Annotations - Additional metadata included in results.</li> <li>Synopsis - A brief description on the intended purpose of the rule.</li> <li>Description - A detailed description on the intended purpose of the rule.</li> <li>Recommendation - A detailed explanation of the requirements to pass the rule.</li> <li>Notes - Any additional information or configuration options.</li> <li>Links - Any links to external references.</li> </ul> <p>See cmdlet help for detailed information on the <code>Get-PSRuleHelp</code> cmdlet.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#online-help","title":"Online help","text":"<p>Rule documentation may optionally include a link to an online version. When included, the <code>-Online</code> parameter can be used to open the online version in the default web browser.</p> <p>For example:</p> <pre><code>Get-PSRuleHelp &lt;rule-name&gt; -Online\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-rules","title":"Creating documentation for rules","text":"<p>Rule documentation is composed of markdown files, one per rule. When creating rules for more then one culture, a separate markdown file is created per rule per culture.</p> <p>The markdown files for each rule is automatically discovered based on naming convention.</p> <p>Markdown is saved in a file with the same filename as the rule name with the <code>.md</code> extension. The file name should match the same case exactly, with a lower case extension.</p> <p>As an example, the <code>storageAccounts.UseHttps.md</code> markdown file would be created.</p> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre> <p>The markdown of each file uses following structure.</p> <pre><code>---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n\n\n{{ A brief summary of the rule }}\n\n## Description\n\n{{ A detailed description of the rule }}\n\n## Recommendation\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## Notes\n\n{{ Additional information or configuration options }}\n\n## Links\n\n{{ Links to external references }}\n</code></pre> <p>Optionally, one or more annotations formatted as YAML key value pairs can be included. i.e. <code>severity: Critical</code></p> <p>Additional sections such as <code>EXAMPLES</code> can be included although are not exposed with <code>Get-PSRuleHelp</code>.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-suppression-groups","title":"Creating documentation for suppression groups","text":"<p>Suppression groups support documentation similar to rules that allows a synopsis to be defined. Other sections can be added to the markdown content, but are ignored. Set the synopsis in markdown to allow a culture specific message to be displayed.</p> <p>The markdown of each file uses following structure.</p> <pre><code>---\n{{ Annotations }}\n---\n\n# {{ Name of suppression group }}\n\n\n\n{{ A brief summary of the suppression group }}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#storing-markdown-files","title":"Storing markdown files","text":"<p>The location PSRule uses to find markdown documentation depends on how the rules/ resources are packaged. In each case, documentation will be in a culture <code>/&lt;culture&gt;/</code>specific subdirectory. Resources can be either shipped as part of a module, or standalone.</p> <ul> <li>When resources are standalone, the culture subdirectory is relative to the <code>*.Rule.*</code> file.</li> <li>When packaged in a module, the culture subdirectory is relative to the module manifest <code>.psd1</code> file.</li> </ul> <p>The <code>&lt;culture&gt;</code> subdirectory will be the current culture that PowerShell is executed under. To determine the current culture use <code>(Get-Culture).Name</code>. Alternatively, the culture can set by using the <code>-Culture</code> parameter of PSRule cmdlets.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#links","title":"Links","text":"<ul> <li>Get-PSRuleHelp</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/","title":"Expressions","text":"<p>Describes PSRule expressions and how to use them.</p>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#description","title":"Description","text":"<p>PSRule expressions are used within YAML-based rules or selectors to evaluate an object. Expressions are comprised of nested conditions, operators, and comparison properties.</p> <p>The following conditions are available:</p> <ul> <li>APIVersion</li> <li>Contains</li> <li>Count</li> <li>Equals</li> <li>EndsWith</li> <li>Exists</li> <li>Greater</li> <li>GreaterOrEquals</li> <li>HasDefault</li> <li>HasSchema</li> <li>HasValue</li> <li>In</li> <li>IsLower</li> <li>IsString</li> <li>IsArray</li> <li>IsBoolean</li> <li>IsDateTime</li> <li>IsInteger</li> <li>IsNumeric</li> <li>IsUpper</li> <li>Less</li> <li>LessOrEquals</li> <li>Like</li> <li>Match</li> <li>NotContains</li> <li>NotCount</li> <li>NotEndsWith</li> <li>NotEquals</li> <li>NotIn</li> <li>NotLike</li> <li>NotMatch</li> <li>NotStartsWith</li> <li>NotWithinPath</li> <li>SetOf</li> <li>StartsWith</li> <li>Subset</li> <li>WithinPath</li> <li>Version</li> </ul> <p>The following operators are available:</p> <ul> <li>AllOf</li> <li>AnyOf</li> <li>Not</li> </ul> <p>The following comparison properties are available:</p> <ul> <li>Field</li> <li>Name</li> <li>Scope</li> <li>Source</li> <li>Type</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#allof","title":"AllOf","text":"<p>The <code>allOf</code> operator is used to require all nested expressions to match. When any nested expression does not match, <code>allOf</code> does not match. This is similar to a logical and operation.</p> <p>Additionally sub-selectors can be used to modify the <code>allOf</code> operator. Sub-selectors allow filtering and looping through arrays of objects before the <code>allOf</code> operator is applied. See sub-selectors for more information.</p> <p>Syntax:</p> <pre><code>allOf: &lt;expression[]&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleAllOf'\nspec:\n  condition:\n    allOf:\n    # Both Name and Description must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'Description'\n      exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAllOf'\nspec:\n  if:\n    allOf:\n    # Both Name and Description must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'Description'\n      exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#anyof","title":"AnyOf","text":"<p>The <code>anyOf</code> operator is used to require one or more nested expressions to match. When any nested expression matches, <code>allOf</code> matches. This is similar to a logical or operation.</p> <p>Additionally sub-selectors can be used to modify the <code>anyOf</code> operator. Sub-selectors allow filtering and looping through arrays of objects before the <code>anyOf</code> operator is applied. See sub-selectors for more information.</p> <p>Syntax:</p> <pre><code>anyOf: &lt;expression[]&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleAnyOf'\nspec:\n  condition:\n    anyOf:\n    # Name and/ or AlternativeName must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'AlternativeName'\n      exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAnyOf'\nspec:\n  if:\n    anyOf:\n    # Name and/ or AlternativeName must exist.\n    - field: 'Name'\n      exists: true\n    - field: 'AlternativeName'\n      exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#apiversion","title":"APIVersion","text":"<p>The <code>apiVersion</code> condition determines if the operand is a valid date version. A constraint can optionally be provided to require the date version to be within a range. Supported version constraints for expression are the same as the <code>$Assert.APIVersion</code> assertion helper.</p> <p>Syntax:</p> <pre><code>apiVersion: &lt;string&gt;\nincludePrerelease: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleAPIVersion'\nspec:\n  condition:\n    field: 'engine.apiVersion'\n    apiVersion: '&gt;=2015-10-01'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAnyAPIVersion'\nspec:\n  if:\n    field: 'engine.apiVersion'\n    apiVersion: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAPIVersionIncludingPrerelease'\nspec:\n  if:\n    field: 'engine.apiVersion'\n    apiVersion: '&gt;=2015-10-01'\n    includePrerelease: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#contains","title":"Contains","text":"<p>The <code>contains</code> condition can be used to determine if the operand contains a specified sub-string. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>contains: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, contains always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleContains'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      contains: '/azure/'\n    - field: 'url'\n      contains:\n      - 'github.io'\n      - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleContains'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      contains: '/azure/'\n    - field: 'url'\n      contains:\n      - 'github.io'\n      - 'github.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#count","title":"Count","text":"<p>The <code>count</code> condition is used to determine if the operand contains a specified number of items.</p> <p>Syntax:</p> <pre><code>count: &lt;int&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleCount'\nspec:\n  condition:\n    field: 'items'\n    count: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleCount'\nspec:\n  if:\n    field: 'items'\n    count: 2\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#equals","title":"Equals","text":"<p>The <code>equals</code> condition can be used to compare if the operand is equal to a supplied value.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   This only applies to string comparisons.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>equals: &lt;string | int | bool&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleEquals'\nspec:\n  condition:\n    field: 'Name'\n    equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleEquals'\nspec:\n  if:\n    field: 'Name'\n    equals: 'TargetObject1'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#endswith","title":"EndsWith","text":"<p>The <code>endsWith</code> condition can be used to determine if the operand ends with a specified string. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>endsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, endsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleEndsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'hostname'\n      endsWith: '.com'\n    - field: 'hostname'\n      endsWith:\n      - '.com.au'\n      - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleEndsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'hostname'\n      endsWith: '.com'\n    - field: 'hostname'\n      endsWith:\n      - '.com.au'\n      - '.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#exists","title":"Exists","text":"<p>The <code>exists</code> condition determines if the specified field exists.</p> <p>Syntax:</p> <pre><code>exists: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>exists: true</code>, exists will return <code>true</code> if the field exists.</li> <li>When <code>exists: false</code>, exists will return <code>true</code> if the field does not exist.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleExists'\nspec:\n  condition:\n    field: 'Name'\n    exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleExists'\nspec:\n  if:\n    field: 'Name'\n    exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#field","title":"Field","text":"<p>The comparison property <code>field</code> is used with a condition to determine field of the object to evaluate. A field can be:</p> <ul> <li>A property name.</li> <li>A key within a hashtable or dictionary.</li> <li>An index in an array or collection.</li> <li>A nested path through an object.</li> </ul> <p>Syntax:</p> <pre><code>field: &lt;string&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleField'\nspec:\n  condition:\n    field: 'Properties.securityRules[0].name'\n    exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleField'\nspec:\n  if:\n    field: 'Properties.securityRules[0].name'\n    exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greater","title":"Greater","text":"<p>The <code>greater</code> condition determines if the operand is greater than a supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>greater: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleGreater'\nspec:\n  condition:\n    field: 'Name'\n    greater: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleGreater'\nspec:\n  if:\n    field: 'Name'\n    greater: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greaterorequals","title":"GreaterOrEquals","text":"<p>The <code>greaterOrEquals</code> condition determines if the operand is greater or equal to the supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>greaterOrEquals: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleGreaterOrEquals'\nspec:\n  condition:\n    field: 'Name'\n    greaterOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleGreaterOrEquals'\nspec:\n  if:\n    field: 'Name'\n    greaterOrEquals: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasdefault","title":"HasDefault","text":"<p>The <code>hasDefault</code> condition determines if the field exists that it is set to the specified value. If the field does not exist, the condition will return <code>true</code>.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed for string values.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>hasDefault: &lt;string | int | bool&gt;\ncaseSensitive: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleHasDefault'\nspec:\n  condition:\n    field: 'enabled'\n    hasDefault: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasDefault'\nspec:\n  if:\n    field: 'enabled'\n    hasDefault: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasschema","title":"HasSchema","text":"<p>The <code>hasSchema</code> condition determines if the operand has a <code>$schema</code> property defined. If the <code>$schema</code> property is defined, it must match one of the specified schemas. If a trailing <code>#</code> is specified it is ignored.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>ignoreScheme</code> - Optionally, the URI scheme is ignored in the comparison.   By default, the scheme is compared.   When <code>true</code>, the schema will match if either <code>http://</code> or <code>https://</code> is specified.</li> </ul> <p>Syntax:</p> <pre><code>hasSchema: &lt;array&gt;\ncaseSensitive: &lt;bool&gt;\nignoreScheme: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>hasSchema: []</code>, hasSchema will return <code>true</code> if any non-empty <code>$schema</code> property is defined.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleHasSchema'\nspec:\n  condition:\n    field: '.'\n    hasSchema:\n    - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasSchema'\nspec:\n  if:\n    field: '.'\n    hasSchema:\n    - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n    - https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#\n    ignoreScheme: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasAnySchema'\nspec:\n  if:\n    field: '.'\n    hasSchema: []\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasvalue","title":"HasValue","text":"<p>The <code>hasValue</code> condition determines if the field exists and has a non-empty value.</p> <p>Syntax:</p> <pre><code>hasValue: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>hasValue: true</code>, hasValue will return <code>true</code> if the field is not empty.</li> <li>When <code>hasValue: false</code>, hasValue will return <code>true</code> if the field is empty.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleHasValue'\nspec:\n  condition:\n    field: 'Name'\n    hasValue: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleHasValue'\nspec:\n  if:\n    field: 'Name'\n    hasValue: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#in","title":"In","text":"<p>The <code>in</code> condition can be used to compare if a field contains one of the specified values.</p> <p>Syntax:</p> <pre><code>in: &lt;array&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIn'\nspec:\n  condition:\n    field: 'Name'\n    in:\n    - 'Value1'\n    - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIn'\nspec:\n  if:\n    field: 'Name'\n    in:\n    - 'Value1'\n    - 'Value2'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#islower","title":"IsLower","text":"<p>The <code>isLower</code> condition determines if the operand is a lowercase string.</p> <p>Syntax:</p> <pre><code>isLower: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isLower: true</code>, isLower will return <code>true</code> if the operand is a lowercase string.   Non-letter characters are ignored.</li> <li>When <code>isLower: false</code>, isLower will return <code>true</code> if the operand is not a lowercase string.</li> <li>If the operand is a field, and the field does not exist isLower always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIsLower'\nspec:\n  condition:\n    field: 'Name'\n    isLower: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIsLower'\nspec:\n  if:\n    field: 'Name'\n    isLower: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isstring","title":"IsString","text":"<p>The <code>isString</code> condition determines if the operand is a string or other type.</p> <p>Syntax:</p> <pre><code>isString: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isString: true</code>, isString will return <code>true</code> if the operand is a string.</li> <li>When <code>isString: false</code>, isString will return <code>true</code> if the operand is not a string or is null.</li> <li>If the operand is a field, and the field does not exist isString always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIsString'\nspec:\n  condition:\n    field: 'Name'\n    isString: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIsString'\nspec:\n  if:\n    field: 'Name'\n    isString: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isarray","title":"IsArray","text":"<p>The <code>isArray</code> condition determines if the operand is an array or other type.</p> <p>Syntax:</p> <pre><code>isArray: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isArray: true</code>, isArray will return <code>true</code> if the operand is an array.</li> <li>When <code>isArray: false</code>, isArray will return <code>true</code> if the operand is not an array or null.</li> <li>If the operand is a field, and the field does not exist, isArray always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isArray\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsArrayExample\nspec:\n  if:\n    field: 'Value'\n    isArray: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isboolean","title":"IsBoolean","text":"<p>The <code>isBoolean</code> condition determines if the operand is a boolean or other type.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to boolean type.   E.g. <code>'true'</code> can be converted to <code>true</code>.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isBoolean: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isBoolean: true</code>, isBoolean will return <code>true</code> if the operand is a boolean.</li> <li>When <code>isBoolean: false</code>, isBoolean will return <code>false</code> if the operand is not a boolean or null.</li> <li>When <code>convert: true</code>, types will be converted to boolean before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isBoolean\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsBooleanExample\nspec:\n  if:\n    field: 'Value'\n    isBoolean: true\n\n---\n# Synopsis: Using isBoolean with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsBooleanExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isBoolean: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isdatetime","title":"IsDateTime","text":"<p>The <code>isDateTime</code> condition determines if the operand is a datetime or other type.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to datetime type.   E.g. <code>'2021-04-03T15:00:00.00+10:00'</code> can be converted to a datetime.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isDateTime: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isDateTime: true</code>, isDateTime will return <code>true</code> if the operand is a datetime.</li> <li>When <code>isDateTime: false</code>, isDateTime will return <code>false</code> if the operand is not a datetime or null.</li> <li>When <code>convert: true</code>, types will be converted to datetime before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isDateTime\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsDateTimeExample\nspec:\n  if:\n    field: 'Value'\n    isDateTime: true\n\n---\n# Synopsis: Using isDateTime with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsDateTimeExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isDateTime: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isinteger","title":"IsInteger","text":"<p>The <code>isInteger</code> condition determines if the operand is a an integer or other type. The following types are considered integer types <code>int</code>, <code>long</code>, <code>byte</code>.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to integer type.   E.g. <code>'123'</code> can be converted to <code>123</code>.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isInteger: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isInteger: true</code>, isInteger will return <code>true</code> if the operand is an integer.</li> <li>When <code>isInteger: false</code>, isInteger will return <code>false</code> if the operand is not an integer or null.</li> <li>When <code>convert: true</code>, types will be converted to integer before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isInteger\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsIntegerExample\nspec:\n  if:\n    field: 'Value'\n    isInteger: true\n\n---\n# Synopsis: Using isInteger with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsIntegerExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isInteger: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isnumeric","title":"IsNumeric","text":"<p>The <code>isNumeric</code> condition determines if the operand is a a numeric or other type. The following types are considered numeric types <code>int</code>, <code>long</code>, <code>float</code>, <code>byte</code>, <code>double</code>.</p> <ul> <li><code>convert</code> - Optionally, types can be converted to numeric type.   E.g. <code>'123'</code> can be converted to <code>123</code>.   By default <code>convert</code> is <code>false</code>.</li> </ul> <pre><code>isNumeric: &lt;bool&gt;\nconvert: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isNumeric: true</code>, isNumeric will return <code>true</code> if the operand is a numeric.</li> <li>When <code>isNumeric: false</code>, isNumeric will return <code>false</code> if the operand is not a numeric or null.</li> <li>When <code>convert: true</code>, types will be converted to numeric before condition is evaluated.</li> </ul> <p>For example:</p> <pre><code>---\n# Synopsis: Using isNumeric\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsNumericExample\nspec:\n  if:\n    field: 'Value'\n    isNumeric: true\n\n---\n# Synopsis: Using isNumeric with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IsNumercExampleWithConversion\nspec:\n  if:\n    field: 'Value'\n    isNumeric: true\n    convert: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isupper","title":"IsUpper","text":"<p>The <code>isUpper</code> condition determines if the operand is an uppercase string.</p> <p>Syntax:</p> <pre><code>isUpper: &lt;bool&gt;\n</code></pre> <ul> <li>When <code>isUpper: true</code>, isUpper will return <code>true</code> if the operand is an uppercase string.   Non-letter characters are ignored.</li> <li>When <code>isUpper: false</code>, isUpper will return <code>true</code> if the operand is not an uppercase string.</li> <li>If the operand is a field, and the field does not exist isUpper always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleIsUpper'\nspec:\n  condition:\n    field: 'Name'\n    isUpper: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleIsUpper'\nspec:\n  if:\n    field: 'Name'\n    isUpper: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#less","title":"Less","text":"<p>The <code>less</code> condition determines if the operand is less than a supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>less: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleLess'\nspec:\n  condition:\n    field: 'Name'\n    less: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleLess'\nspec:\n  if:\n    field: 'Name'\n    less: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#lessorequals","title":"LessOrEquals","text":"<p>The <code>lessOrEquals</code> condition determines if the operand is less or equal to the supplied value. The field value can either be an integer, float, array, or string.</p> <ul> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>When the field value is:</p> <ul> <li>An integer or float, a numerical comparison is used.</li> <li>An array, the number of elements is compared.</li> <li>A string, the length of the string is compared.   If <code>convert</code> is <code>true</code>, the string is converted a number instead.</li> <li>A DateTime, the number of days from the current time is compared.</li> </ul> <p>Syntax:</p> <pre><code>lessOrEquals: &lt;int&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleLessOrEquals'\nspec:\n  condition:\n    field: 'Name'\n    lessOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleLessOrEquals'\nspec:\n  if:\n    field: 'Name'\n    lessOrEquals: 3\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#like","title":"Like","text":"<p>The <code>like</code> condition can be used to determine if the operand matches a wildcard pattern. One or more patterns to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>like: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, like always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleLike'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      like: 'http://*'\n    - field: 'url'\n      like:\n      - 'http://*'\n      - 'https://*'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleLike'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      like: 'http://*'\n    - field: 'url'\n      like:\n      - 'http://*'\n      - 'https://*'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#match","title":"Match","text":"<p>The <code>match</code> condition can be used to compare if a field matches a supplied regular expression.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>match: &lt;string&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleMatch'\nspec:\n  condition:\n    field: 'Name'\n    match: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleMatch'\nspec:\n  if:\n    field: 'Name'\n    match: '$(abc|efg)$'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#name","title":"Name","text":"<p>The comparison property <code>name</code> is used with a condition to evaluate the target name of the object. The <code>name</code> property must be set to <code>.</code>. Any other value will cause the condition to evaluate to <code>false</code>.</p> <p>Syntax:</p> <pre><code>name: '.'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleName'\nspec:\n  condition:\n    name: '.'\n    equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleName'\nspec:\n  if:\n    name: '.'\n    in:\n    - 'TargetObject1'\n    - 'TargetObject2'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#not","title":"Not","text":"<p>The <code>any</code> operator is used to invert the result of the nested expression. When a nested expression matches, <code>not</code> does not match. When a nested expression does not match, <code>not</code> matches.</p> <p>Syntax:</p> <pre><code>not: &lt;expression&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNot'\nspec:\n  condition:\n    not:\n      # The AlternativeName field must not exist.\n      field: 'AlternativeName'\n      exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNot'\nspec:\n  if:\n    not:\n      # The AlternativeName field must not exist.\n      field: 'AlternativeName'\n      exists: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcontains","title":"NotContains","text":"<p>The <code>notContains</code> condition can be used to determine if the operand contains a specified sub-string. This condition fails when any of the specified sub-strings are found in the operand. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notContains: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notContains always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotContains'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      notContains: '/azure/'\n    - field: 'url'\n      notContains:\n      - 'github.io'\n      - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotContains'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      notContains: '/azure/'\n    - field: 'url'\n      notContains:\n      - 'github.io'\n      - 'github.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcount","title":"NotCount","text":"<p>The <code>notCount</code> condition is used to determine if the operand does not contain a specified number of items.</p> <p>Syntax:</p> <pre><code>notCount: &lt;int&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotCount'\nspec:\n  condition:\n    field: 'items'\n    notCount: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotCount'\nspec:\n  if:\n    field: 'items'\n    notCount: 2\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notendswith","title":"NotEndsWith","text":"<p>The <code>notEndsWith</code> condition can be used to determine if the operand ends with a specified string. This condition fails when any of the specified sub-strings are found at the end of the operand. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notEndsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notEndsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotEndsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'hostname'\n      notEndsWith: '.com'\n    - field: 'hostname'\n      notEndsWith:\n      - '.com.au'\n      - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotEndsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'hostname'\n      notEndsWith: '.com'\n    - field: 'hostname'\n      notEndsWith:\n      - '.com.au'\n      - '.com'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notequals","title":"NotEquals","text":"<p>The <code>notEquals</code> condition can be used to compare if a field is equal to a supplied value.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   This only applies to string comparisons.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, perform type conversion on operand type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notEquals: &lt;string | int | bool&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotEquals'\nspec:\n  condition:\n    field: 'Name'\n    notEquals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotEquals'\nspec:\n  if:\n    field: 'Name'\n    notEquals: 'TargetObject1'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notin","title":"NotIn","text":"<p>The <code>notIn</code> condition can be used to compare if a field does not contains one of the specified values.</p> <p>Syntax:</p> <pre><code>notIn: &lt;array&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotIn'\nspec:\n  condition:\n    field: 'Name'\n    notIn:\n    - 'Value1'\n    - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotIn'\nspec:\n  if:\n    field: 'Name'\n    notIn:\n    - 'Value1'\n    - 'Value2'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notlike","title":"NotLike","text":"<p>The <code>notLike</code> condition can be used to determine if the operand matches a wildcard pattern. This condition fails when any of the specified patterns match the operand. One or more patterns to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notLike: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notLike always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotLike'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      notLike: 'http://*'\n    - field: 'url'\n      notLike:\n      - 'http://'\n      - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotLike'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      notLike: 'http://*'\n    - field: 'url'\n      notLike:\n      - 'http://'\n      - 'https://'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notmatch","title":"NotMatch","text":"<p>The <code>notMatch</code> condition can be used to compare if a field does not matches a supplied regular expression.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>notMatch: &lt;string&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotMatch'\nspec:\n  condition:\n    field: 'Name'\n    notMatch: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotMatch'\nspec:\n  if:\n    field: 'Name'\n    notMatch: '$(abc|efg)$'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notstartswith","title":"NotStartsWith","text":"<p>The <code>notStartsWith</code> condition can be used to determine if the operand starts with a specified string. This condition fails when any of the specified sub-strings are found at the start of the operand. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>notStartsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, notStartsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleNotStartsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      notStartsWith: 'http'\n    - field: 'url'\n      notStartsWith:\n      - 'http://'\n      - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleNotStartsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      notStartsWith: 'http'\n    - field: 'url'\n      notStartsWith:\n      - 'http://'\n      - 'https://'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notwithinpath","title":"NotWithinPath","text":"<p>The <code>notWithinPath</code> condition determines if a file path is not within a required path.</p> <p>If the path is not within the required path, the condition will return <code>true</code>. If the path is within the required path, the condition will return <code>false</code>.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed for string values.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>notWithinPath: &lt;array&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\n# Synopsis: Test notWithinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceNotWithinPath\nspec:\n  if:\n    source: 'Template'\n    notWithinPath:\n      - \"deployments/path/\"\n\n---\n# Synopsis: Test notWithinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceNotWithinPathCaseSensitive\nspec:\n  if:\n    source: 'Template'\n    notWithinPath:\n      - \"Deployments/Path/\"\n    caseSensitive: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#scope","title":"Scope","text":"<p>The comparison property <code>scope</code> is used with a condition to evaluate any scopes assigned to the object. The <code>scope</code> property must be set to <code>.</code>. Any other value will cause the condition to evaluate to <code>false</code>.</p> <p>Syntax:</p> <pre><code>scope: '.'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleScope'\nspec:\n  condition:\n    scope: '.'\n    startsWith: '/'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleScope'\nspec:\n  if:\n    scope: '.'\n    startsWith: '/'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#setof","title":"SetOf","text":"<p>The <code>setOf</code> condition can be used to determine if the operand is a set of specified values. Additionally the following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>setOf: &lt;array&gt;\ncaseSensitive: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleSetOf'\nspec:\n  condition:\n    field: 'zones'\n    setOf:\n    - 1\n    - 2\n    - 3\n    caseSensitive: false\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleSetOf'\nspec:\n  if:\n    field: 'zones'\n    setOf:\n    - 1\n    - 2\n    - 3\n    caseSensitive: false\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#source","title":"Source","text":"<p>The comparison property <code>source</code> is used with a condition to expose the source path for the resource. The <code>source</code> property can be set to any value. The default is <code>file</code> when objects loaded from a file don't identify a source.</p> <p>Syntax:</p> <pre><code>source: 'file'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: IgnoreTestFiles\nspec:\n  if:\n    source: 'file'\n    withinPath: 'tests/PSRule.Tests/'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#startswith","title":"StartsWith","text":"<p>The <code>startsWith</code> condition can be used to determine if the operand starts with a specified string. One or more strings to compare can be specified.</p> <ul> <li><code>caseSensitive</code> - Optionally, a case sensitive-comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>convert</code> - Optionally, types can be converted to string type.   By default <code>convert</code> is <code>false</code>.</li> </ul> <p>Syntax:</p> <pre><code>startsWith: &lt;string | array&gt;\ncaseSensitive: &lt;boolean&gt;\nconvert: &lt;boolean&gt;\n</code></pre> <ul> <li>If the operand is a field, and the field does not exist, startsWith always returns <code>false</code>.</li> </ul> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleStartsWith'\nspec:\n  condition:\n    anyOf:\n    - field: 'url'\n      startsWith: 'http'\n    - field: 'url'\n      startsWith:\n      - 'http://'\n      - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleStartsWith'\nspec:\n  if:\n    anyOf:\n    - field: 'url'\n      startsWith: 'http'\n    - field: 'url'\n      startsWith:\n      - 'http://'\n      - 'https://'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#subset","title":"Subset","text":"<p>The <code>subset</code> condition can be used to determine if the operand is a set of specified values. The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed.   By default, case-insensitive comparison is performed.</li> <li><code>unique</code> - Optionally, the operand must not contain duplicates.   By default, duplicates are allowed.</li> </ul> <p>Syntax:</p> <pre><code>subset: &lt;array&gt;\ncaseSensitive: &lt;bool&gt;\nunique: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleSubset'\nspec:\n  condition:\n    field: 'logs'\n    subset:\n    - 'cluster-autoscaler'\n    - 'kube-apiserver'\n    - 'kube-scheduler'\n    caseSensitive: true\n    unique: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleSubset'\nspec:\n  if:\n    field: 'logs'\n    subset:\n    - 'cluster-autoscaler'\n    - 'kube-apiserver'\n    - 'kube-scheduler'\n    caseSensitive: true\n    unique: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#type","title":"Type","text":"<p>The comparison property <code>type</code> is used with a condition to evaluate the target type of the object. The <code>type</code> property must be set to <code>.</code>. Any other value will cause the condition to evaluate to <code>false</code>.</p> <p>Syntax:</p> <pre><code>type: '.'\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleType'\nspec:\n  condition:\n    type: '.'\n    equals: 'CustomType'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleType'\nspec:\n  if:\n    type: '.'\n    in:\n    - 'Microsoft.Storage/storageAccounts'\n    - 'Microsoft.Storage/storageAccounts/blobServices'\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#version","title":"Version","text":"<p>The <code>version</code> condition determines if the operand is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range. Supported version constraints for expression are the same as the <code>$Assert.Version</code> assertion helper.</p> <p>Syntax:</p> <pre><code>version: &lt;string&gt;\nincludePrerelease: &lt;bool&gt;\n</code></pre> <p>For example:</p> <pre><code>---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'ExampleVersion'\nspec:\n  condition:\n    field: 'engine.version'\n    version: '^1.2.3'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleAnyVersion'\nspec:\n  if:\n    field: 'engine.version'\n    version: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: 'ExampleVersionIncludingPrerelease'\nspec:\n  if:\n    field: 'engine.version'\n    version: '&gt;=1.5.0'\n    includePrerelease: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#withinpath","title":"WithinPath","text":"<p>The <code>withinPath</code> condition determines if a file path is within a required path.</p> <p>If the path is within the required path, the condition will return <code>true</code>. If the path is not within the required path, the condition will return <code>false</code>.</p> <p>The following properties are accepted:</p> <ul> <li><code>caseSensitive</code> - Optionally, a case-sensitive comparison can be performed for string values.   By default, case-insensitive comparison is performed.</li> </ul> <p>Syntax:</p> <pre><code>withinPath: &lt;array&gt;\ncaseSensitive: &lt;boolean&gt;\n</code></pre> <p>For example:</p> <pre><code>---\n# Synopsis: Test withinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceWithinPath\nspec:\n  if:\n    source: 'Template'\n    withinPath:\n      - \"deployments/path/\"\n\n---\n# Synopsis: Test withinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: YamlSourceWithinPathCaseSensitive\nspec:\n  if:\n    source: 'Template'\n    withinPath:\n      - \"Deployments/Path/\"\n    caseSensitive: true\n</code></pre>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Options/","title":"Options","text":"<p>Describes additional options that can be used during rule execution.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#description","title":"Description","text":"<p>PSRule lets you use options when calling cmdlets such as <code>Invoke-PSRule</code> and <code>Test-PSRuleTarget</code> to change how rules are processed. This topic describes what options are available, when to and how to use them.</p> <p>The following workspace options are available for use:</p> <ul> <li>Baseline.Group</li> <li>Convention.Include</li> <li>Execution.AliasReference</li> <li>Execution.DuplicateResourceId</li> <li>Execution.HashAlgorithm</li> <li>Execution.LanguageMode</li> <li>Execution.InvariantCulture</li> <li>Execution.InitialSessionState</li> <li>Execution.RestrictScriptSource</li> <li>Execution.RuleInconclusive</li> <li>Execution.SuppressionGroupExpired</li> <li>Execution.UnprocessedObject</li> <li>Include.Module</li> <li>Include.Path</li> <li>Input.Format</li> <li>Input.IgnoreGitPath</li> <li>Input.IgnoreObjectSource</li> <li>Input.IgnoreRepositoryCommon</li> <li>Input.IgnoreUnchangedPath</li> <li>Input.ObjectPath</li> <li>Input.PathIgnore</li> <li>Input.TargetType</li> <li>Logging.LimitDebug</li> <li>Logging.LimitVerbose</li> <li>Logging.RuleFail</li> <li>Logging.RulePass</li> <li>Output.As</li> <li>Output.Banner</li> <li>Output.Culture</li> <li>Output.Encoding</li> <li>Output.Footer</li> <li>Output.Format</li> <li>Output.JobSummaryPath</li> <li>Output.JsonIndent</li> <li>Output.Outcome</li> <li>Output.Path</li> <li>Output.SarifProblemsOnly</li> <li>Output.Style</li> <li>Repository.BaseRef</li> <li>Repository.Url</li> <li>Requires</li> <li>Suppression</li> </ul> <p>Additionally the following baseline options can be included:</p> <ul> <li>Binding.Field</li> <li>Binding.IgnoreCase</li> <li>Binding.NameSeparator</li> <li>Binding.PreferTargetInfo</li> <li>Binding.TargetName</li> <li>Binding.TargetType</li> <li>Binding.UseQualifiedName</li> <li>Configuration</li> <li>Rule.Baseline</li> <li>Rule.Include</li> <li>Rule.IncludeLocal</li> <li>Rule.Exclude</li> <li>Rule.Tag</li> </ul> <p>See about_PSRule_Baseline for more information on baseline options.</p> <p>Options can be used with the following PSRule cmdlets:</p> <ul> <li>Export-PSRuleBaseline</li> <li>Get-PSRule</li> <li>Get-PSRuleBaseline</li> <li>Get-PSRuleHelp</li> <li>Invoke-PSRule</li> <li>Test-PSRuleTarget</li> </ul> <p>Each of these cmdlets support:</p> <ul> <li>Using the <code>-Option</code> parameter with an object created with the <code>New-PSRuleOption</code> cmdlet.   See cmdlet help for syntax and examples.</li> <li>Using the <code>-Option</code> parameter with a hashtable object.</li> <li>Using the <code>-Option</code> parameter with a YAML file path.</li> </ul> <p>When using a hashtable object <code>@{}</code>, one or more options can be specified as keys using a dotted notation.</p> <p>For example:</p> <pre><code>$option = @{ 'Output.Format' = 'Yaml' };\nInvoke-PSRule -Path . -Option $option;\n</code></pre> <pre><code>Invoke-PSRule -Path . -Option @{ 'Output.Format' = 'Yaml' };\n</code></pre> <p>The above example shows how the <code>Output.Format</code> option as a hashtable key can be used. Continue reading for a full list of options and how each can be used.</p> <p>Alternatively, options can be stored in a YAML formatted file and loaded from disk. Storing options as YAML allows different configurations to be loaded in a repeatable way instead of having to create an options object each time.</p> <p>Options are stored as YAML properties using a lower camel case naming convention, for example:</p> <pre><code>output:\n  format: Yaml\n</code></pre> <p>The <code>Set-PSRuleOption</code> cmdlet can be used to set options stored in YAML or the YAML file can be manually edited.</p> <pre><code>Set-PSRuleOption -OutputFormat Yaml;\n</code></pre> <p>By default, PSRule will automatically look for a default YAML options file in the current working directory. Alternatively, you can specify a specific file path.</p> <p>For example:</p> <pre><code>Invoke-PSRule -Option '.\\myconfig.yml';\n</code></pre> <pre><code>New-PSRuleOption -Path '.\\myconfig.yaml';\n</code></pre> <p>PSRule uses any of the following file names (in order) as the default YAML options file. If more than one of these files exist, the following order will be used to find the first match.</p> <ul> <li><code>ps-rule.yaml</code></li> <li><code>ps-rule.yml</code></li> <li><code>psrule.yaml</code></li> <li><code>psrule.yml</code></li> </ul> <p>We recommend only using lowercase characters as shown above. This is because not all operating systems treat case in the same way.</p> <p>Most options can be set using environment variables. When configuring environment variables we recommend that all capital letters are used. This is because environment variables are case-sensitive on some operating systems.</p> <p>PSRule environment variables use a consistent naming pattern of <code>PSRULE_&lt;PARENT&gt;_&lt;NAME&gt;</code>. Where <code>&lt;PARENT&gt;</code> is the parent class and <code>&lt;NAME&gt;</code> is the specific option. For example:</p> <ul> <li><code>Execution.InconclusiveWarning</code> is configured by <code>PSRULE_EXECUTION_INCONCLUSIVEWARNING</code>.</li> <li><code>Input.TargetType</code> is configured by <code>PSRULE_INPUT_TARGETTYPE</code>.</li> <li><code>Output.Format</code> is configured by <code>PSRULE_OUTPUT_FORMAT</code>.</li> </ul> <p>When setting environment variables:</p> <ul> <li>Enum values are set by string. For example <code>PSRULE_OUTPUT_FORMAT</code> could be set to <code>Yaml</code>. Enum values are case-insensitive.</li> <li>Boolean values are set by <code>true</code>, <code>false</code>, <code>1</code>, or <code>0</code>. For example <code>PSRULE_EXECUTION_INCONCLUSIVEWARNING</code> could be set to <code>false</code>. Boolean values are case-insensitive.</li> <li>String array values can specify multiple items by using a semi-colon separator. For example <code>PSRULE_INPUT_TARGETTYPE</code> could be set to <code>virtualMachine;virtualNetwork</code>.</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#baselinegroup","title":"Baseline.Group","text":"<p>You can use a baseline group to provide a friendly name to an existing baseline. When you run PSRule you can opt to use the baseline group name as an alternative name for the baseline. To indicate a baseline group, prefix the group name with <code>@</code> where you would use the name of a baseline.</p> <p>Baseline groups can be specified using:</p> <pre><code># PowerShell: Using the BaselineGroup parameter\n$option = New-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n</code></pre> <pre><code># PowerShell: Using the Baseline.Group hashtable key\n$option = New-PSRuleOption -Option @{ 'Baseline.Group' = @{ latest = 'YourBaseline' } };\n</code></pre> <pre><code># PowerShell: Using the BaselineGroup parameter to set YAML\nSet-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n</code></pre> <pre><code># YAML: Using the baseline/group property\nbaseline:\n  group:\n    latest: YourBaseline\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BASELINE_GROUP='latest=YourBaseline'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BASELINE_GROUP: 'latest=YourBaseline'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BASELINE_GROUP\n  value: 'latest=YourBaseline'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingfield","title":"Binding.Field","text":"<p>When an object is passed from the pipeline, PSRule automatically extracts fields from object properties. PSRule provides standard fields such as <code>TargetName</code> and <code>TargetType</code>. In addition to standard fields, custom fields can be bound. Custom fields are available to rules and included in output.</p> <p>PSRule uses the following logic to determine which property should be used for binding:</p> <ul> <li>By default PSRule will not extract any custom fields.</li> <li>If custom fields are configured, PSRule will attempt to bind the field.<ul> <li>If none of the configured property names exist, the field will be skipped.</li> <li>If more then one property name is configured, the order they are specified in the configuration determines precedence.<ul> <li>i.e. The first configured property name will take precedence over the second property name.</li> </ul> </li> <li>By default the property name will be matched ignoring case sensitivity.   To use a case sensitive match, configure the Binding.IgnoreCase option.</li> </ul> </li> </ul> <p>Custom field bindings can be specified using:</p> <pre><code># PowerShell: Using the BindingField parameter\n$option = New-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n</code></pre> <pre><code># PowerShell: Using the Binding.Field hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.Field' = @{ id = 'ResourceId', 'AlternativeId' } };\n</code></pre> <pre><code># PowerShell: Using the BindingField parameter to set YAML\nSet-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n</code></pre> <pre><code># YAML: Using the binding/field property\nbinding:\n  field:\n    id:\n    - ResourceId\n    - AlternativeId\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingignorecase","title":"Binding.IgnoreCase","text":"<p>When evaluating an object, PSRule extracts a few key properties from the object to help filter rules and display output results. The process of extract these key properties is called binding. The properties that PSRule uses for binding can be customized by providing a order list of alternative properties to use. See <code>Binding.TargetName</code> and <code>Binding.TargetType</code> for these options.</p> <ul> <li>By default, custom property binding finds the first matching property by name regardless of case. i.e. <code>Binding.IgnoreCase</code> is <code>true</code>.</li> <li>To make custom bindings case sensitive, set the <code>Binding.IgnoreCase</code> option to <code>false</code>.<ul> <li>Changing this option will affect custom property bindings for both TargetName and TargetType.</li> <li>Setting this option has no affect on binding defaults or custom scripts.</li> </ul> </li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingIgnoreCase parameter\n$option = New-PSRuleOption -BindingIgnoreCase $False;\n</code></pre> <pre><code># PowerShell: Using the Binding.IgnoreCase hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.IgnoreCase' = $False };\n</code></pre> <pre><code># PowerShell: Using the BindingIgnoreCase parameter to set YAML\nSet-PSRuleOption -BindingIgnoreCase $False;\n</code></pre> <pre><code># YAML: Using the binding/ignoreCase property\nbinding:\n  ignoreCase: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_IGNORECASE=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_IGNORECASE: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_IGNORECASE\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingnameseparator","title":"Binding.NameSeparator","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.</p> <p>In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName</p> <p>To use a qualified name, see the <code>Binding.UseQualifiedName</code> option.</p> <p>By default, PSRule uses <code>/</code> to separate TargetType from TargetName. This option configures the separator that PSRule uses between the two components.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingNameSeparator parameter\n$option = New-PSRuleOption -BindingNameSeparator '::';\n</code></pre> <pre><code># PowerShell: Using the Binding.NameSeparator hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.NameSeparator' = '::' };\n</code></pre> <pre><code># PowerShell: Using the BindingNameSeparator parameter to set YAML\nSet-PSRuleOption -BindingNameSeparator '::';\n</code></pre> <pre><code># YAML: Using the binding/nameSeparator property\nbinding:\n  nameSeparator: '::'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_NAMESEPARATOR='::'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_NAMESEPARATOR: '::'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_NAMESEPARATOR\n  value: '::'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingprefertargetinfo","title":"Binding.PreferTargetInfo","text":"<p>Some built-in objects within PSRule perform automatic binding of TargetName and TargetType. These built-in objects provide their own target info.</p> <p>When binding has been configured these values override automatic binding by default. This can occur when the built-in object uses one of the fields specified by the custom configuration. The common occurrences of this are on fields such as <code>Name</code> and <code>FullName</code> which are widely used. To prefer automatic binding when specified set this option to <code>$True</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingPreferTargetInfo parameter\n$option = New-PSRuleOption -BindingPreferTargetInfo $True;\n</code></pre> <pre><code># PowerShell: Using the Binding.PreferTargetInfo hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.PreferTargetInfo' = $True };\n</code></pre> <pre><code># PowerShell: Using the BindingPreferTargetInfo parameter to set YAML\nSet-PSRuleOption -BindingPreferTargetInfo $True;\n</code></pre> <pre><code># YAML: Using the binding/preferTargetInfo property\nbinding:\n  preferTargetInfo: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_PREFERTARGETINFO=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_PREFERTARGETINFO: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_PREFERTARGETINFO\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargetname","title":"Binding.TargetName","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another. Many objects could be passed down the pipeline at the same time, so using a TargetName that is meaningful is important. TargetName is also used for advanced features such as rule suppression.</p> <p>The value that PSRule uses for TargetName is configurable. PSRule uses the following logic to determine what TargetName should be used:</p> <ul> <li>By default PSRule will:<ul> <li>Use <code>TargetName</code> or <code>Name</code> properties on the object. These property names are case insensitive.</li> <li>If both <code>TargetName</code> and <code>Name</code> properties exist, <code>TargetName</code> will take precedence over <code>Name</code>.</li> <li>If neither <code>TargetName</code> or <code>Name</code> properties exist, a hash of the object will be used as TargetName.</li> <li>The hash algorithm used can be set by the <code>Execution.HashAlgorithm</code> option.</li> </ul> </li> <li>If custom TargetName binding properties are configured, the property names specified will override the defaults.<ul> <li>If none of the configured property names exist, PSRule will revert back to <code>TargetName</code> then <code>Name</code>.</li> <li>If more then one property name is configured, the order they are specified in the configuration determines precedence.<ul> <li>i.e. The first configured property name will take precedence over the second property name.</li> </ul> </li> <li>By default the property name will be matched ignoring case sensitivity.   To use a case sensitive match, configure the Binding.IgnoreCase option.</li> </ul> </li> <li>If a custom TargetName binding function is specified, the function will be evaluated first before any other option.<ul> <li>If the function returns <code>$Null</code> then custom properties, <code>TargetName</code> and <code>Name</code> properties will be used.</li> <li>The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.</li> <li>Custom binding functions are blocked in constrained language mode is used.   See language mode for more information.</li> </ul> </li> </ul> <p>Custom property names to use for binding can be specified using:</p> <pre><code># PowerShell: Using the TargetName parameter\n$option = New-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n</code></pre> <pre><code># PowerShell: Using the Binding.TargetName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetName' = 'ResourceName', 'AlternateName' };\n</code></pre> <pre><code># PowerShell: Using the TargetName parameter to set YAML\nSet-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n</code></pre> <pre><code># YAML: Using the binding/targetName property\nbinding:\n  targetName:\n  - ResourceName\n  - AlternateName\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_TARGETNAME='ResourceName;AlternateName'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_TARGETNAME: 'ResourceName;AlternateName'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETNAME\n  value: 'ResourceName;AlternateName'\n</code></pre> <p>To specify a custom binding function use:</p> <pre><code># Create a custom function that returns a TargetName string\n$bindFn = {\n    param ($TargetObject)\n\n    $otherName = $TargetObject.PSObject.Properties['OtherName'];\n    if ($Null -eq $otherName) { return $Null }\n    return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargettype","title":"Binding.TargetType","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetType. TargetType is used to filter rules based on object type and appears in output results.</p> <p>The value that PSRule uses for TargetType is configurable. PSRule uses the following logic to determine what TargetType should be used:</p> <ul> <li>By default PSRule will:<ul> <li>Use the default type presented by PowerShell from <code>TypeNames</code>. i.e. <code>.PSObject.TypeNames[0]</code></li> </ul> </li> <li>If custom TargetType binding properties are configured, the property names specified will override the defaults.<ul> <li>If none of the configured property names exist, PSRule will revert back to the type presented by PowerShell.</li> <li>If more then one property name is configured, the order they are specified in the configuration determines precedence.<ul> <li>i.e. The first configured property name will take precedence over the second property name.</li> </ul> </li> <li>By default the property name will be matched ignoring case sensitivity.   To use a case sensitive match, configure the <code>Binding.IgnoreCase</code> option.</li> </ul> </li> <li>If a custom TargetType binding function is specified, the function will be evaluated first before any other option.<ul> <li>If the function returns <code>$Null</code> then custom properties, or the type presented by PowerShell will be used in order instead.</li> <li>The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.</li> <li>Custom binding functions are blocked in constrained language mode is used.   See language mode for more information.</li> </ul> </li> </ul> <p>Custom property names to use for binding can be specified using:</p> <pre><code># PowerShell: Using the TargetType parameter\n$option = New-PSRuleOption -TargetType 'ResourceType', 'kind';\n</code></pre> <pre><code># PowerShell: Using the Binding.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetType' = 'ResourceType', 'kind' };\n</code></pre> <pre><code># PowerShell: Using the TargetType parameter to set YAML\nSet-PSRuleOption -TargetType 'ResourceType', 'kind';\n</code></pre> <pre><code># YAML: Using the binding/targetType property\nbinding:\n  targetType:\n  - ResourceType\n  - kind\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_TARGETTYPE='ResourceType;kind'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_TARGETTYPE: 'ResourceType;kind'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETTYPE\n  value: 'ResourceType;kind'\n</code></pre> <p>To specify a custom binding function use:</p> <pre><code># Create a custom function that returns a TargetType string\n$bindFn = {\n    param ($TargetObject)\n\n    $otherType = $TargetObject.PSObject.Properties['OtherType'];\n\n    if ($otherType -eq $Null) {\n        return $Null\n    }\n\n    return $otherType.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetType $bindFn;\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingusequalifiedname","title":"Binding.UseQualifiedName","text":"<p>When an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.</p> <p>In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName</p> <p>This option determines if PSRule uses qualified or unqualified names (default).</p> <p>By default, PSRule uses <code>/</code> to separate TargetType from TargetName. Set <code>Binding.NameSeparator</code> to change.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the BindingUseQualifiedName parameter\n$option = New-PSRuleOption -BindingUseQualifiedName $True;\n</code></pre> <pre><code># PowerShell: Using the Binding.UseQualifiedName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.UseQualifiedName' = $True };\n</code></pre> <pre><code># PowerShell: Using the BindingUseQualifiedName parameter to set YAML\nSet-PSRuleOption -BindingUseQualifiedName $True;\n</code></pre> <pre><code># YAML: Using the binding/useQualifiedName property\nbinding:\n  useQualifiedName: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_BINDING_USEQUALIFIEDNAME=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_BINDING_USEQUALIFIEDNAME: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_USEQUALIFIEDNAME\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#configuration","title":"Configuration","text":"<p>Configures a set of baseline configuration values that can be used in rule definitions. Configuration values can be overridden at different scopes.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Configuration option with a hashtable\n$option = New-PSRuleOption -Configuration @{ LOCAL_APPSERVICEMININSTANCECOUNT = 2 };\n</code></pre> <pre><code># YAML: Using the configuration property\nconfiguration:\n  LOCAL_APPSERVICEMININSTANCECOUNT: 2\n</code></pre> <p>Configuration values can be specified using environment variables. To specify a configuration value, prefix the configuration value with <code>PSRULE_CONFIGURATION_</code>.</p> <pre><code># Bash: Using environment variable\nexport PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT=2\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT: '2'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT\n  value: '2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#conventioninclude","title":"Convention.Include","text":"<p>Specifies conventions to execute when the pipeline run. Conventions are included by name and must be defined within files included in <code>-Path</code> or <code>-Module</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Convention parameter\n$option = New-PSRuleOption -Convention 'Convention1', 'Convention2';\n</code></pre> <pre><code># PowerShell: Using the Convention.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Convention.Include' = $True };\n</code></pre> <pre><code># PowerShell: Using the Convention parameter to set YAML\nSet-PSRuleOption -Convention 'Convention1', 'Convention2';\n</code></pre> <pre><code># YAML: Using the convention/include property\nconvention:\n  include:\n  - 'Convention1'\n  - 'Convention2'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_CONVENTION_INCLUDE='Convention1;Convention2'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_CONVENTION_INCLUDE: 'Convention1;Convention2'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONVENTION_INCLUDE\n  value: 'Convention1;Convention2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionaliasreference","title":"Execution.AliasReference","text":"<p> v2.9.0</p> <p>Determines how to handle when an alias to a resource is used. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionAliasReference parameter\n$option = New-PSRuleOption -ExecutionAliasReference 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.AliasReference hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.AliasReference' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionAliasReference parameter to set YAML\nSet-PSRuleOption -ExecutionAliasReference 'Error';\n</code></pre> <pre><code># YAML: Using the execution/aliasReference property\nexecution:\n  aliasReference: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_ALIASREFERENCE=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_ALIASREFERENCE: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_ALIASREFERENCE\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionduplicateresourceid","title":"Execution.DuplicateResourceId","text":"<p> v2.4.0</p> <p>Determines how to handle duplicate resources identifiers during execution. A duplicate resource identifier may exist if two resources are defined with the same name, ref, or alias. By default, an error is thrown, however this behavior can be modified by this option.</p> <p>If this option is configured to <code>Warn</code> or <code>Ignore</code> only the first resource will be used, however PSRule will continue to execute.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Error</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.</li> <li><code>Error</code> (3) - Abort and throw an error.   This is the default.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the DuplicateResourceId parameter\n$option = New-PSRuleOption -DuplicateResourceId 'Warn';\n</code></pre> <pre><code># PowerShell: Using the Execution.DuplicateResourceId hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.DuplicateResourceId' = 'Warn' };\n</code></pre> <pre><code># PowerShell: Using the DuplicateResourceId parameter to set YAML\nSet-PSRuleOption -DuplicateResourceId 'Warn';\n</code></pre> <pre><code># YAML: Using the execution/duplicateResourceId property\nexecution:\n  duplicateResourceId: Warn\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_DUPLICATERESOURCEID=Warn\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_DUPLICATERESOURCEID: Warn\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_DUPLICATERESOURCEID\n  value: Warn\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionhashalgorithm","title":"Execution.HashAlgorithm","text":"<p> v3.0.0</p> <p>Specifies the hashing algorithm used by the PSRule runtime. This hash algorithm is used when generating a resource identifier for an object that does not have a bound name.</p> <p>By default, the SHA512 algorithm is used.</p> <p>The following algorithms are available for use in PSRule:</p> <ul> <li><code>SHA512</code></li> <li><code>SHA384</code></li> <li><code>SHA256</code></li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Execution.HashAlgorithm hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.HashAlgorithm' = 'SHA256' };\n</code></pre> <pre><code># YAML: Using the execution/hashAlgorithm property\nexecution:\n  hashAlgorithm: SHA256\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_HASHALGORITHM=SHA256\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_HASHALGORITHM: SHA256\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_HASHALGORITHM\n  value: SHA256\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionlanguagemode","title":"Execution.LanguageMode","text":"<p>Unless PowerShell has been constrained, full language features of PowerShell are available to use within rule definitions. In locked down environments, a reduced set of language features may be desired.</p> <p>When PSRule is executed in an environment configured for Device Guard, only constrained language features are available.</p> <p>The following language modes are available for use in PSRule:</p> <ul> <li><code>FullLanguage</code> - Executes with all language features.   This is the default.</li> <li><code>ConstrainedLanguage</code> - Executes in constrained language mode that restricts the types and methods that can be used.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Execution.LanguageMode hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.LanguageMode' = 'ConstrainedLanguage' };\n</code></pre> <pre><code># YAML: Using the execution/languageMode property\nexecution:\n  languageMode: ConstrainedLanguage\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_LANGUAGEMODE=ConstrainedLanguage\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_LANGUAGEMODE: ConstrainedLanguage\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_LANGUAGEMODE\n  value: ConstrainedLanguage\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninvariantculture","title":"Execution.InvariantCulture","text":"<p> v2.9.0</p> <p>Determines how to report when an invariant culture is used. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionInvariantCulture parameter\n$option = New-PSRuleOption -ExecutionInvariantCulture 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.InvariantCulture hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InvariantCulture' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionInvariantCulture parameter to set YAML\nSet-PSRuleOption -ExecutionInvariantCulture 'Error';\n</code></pre> <pre><code># YAML: Using the execution/invariantCulture property\nexecution:\n  invariantCulture: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_INVARIANTCULTURE=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_INVARIANTCULTURE: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INVARIANTCULTURE\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninitialsessionstate","title":"Execution.InitialSessionState","text":"<p> v2.5.0</p> <p>Determines how the initial session state for executing PowerShell code is created.</p> <p>The following preferences are available:</p> <ul> <li><code>BuiltIn</code> (0) - Create the initial session state with all built-in cmdlets loaded.   This is the default.</li> <li><code>Minimal</code> (1) - Create the initial session state with only a minimum set of cmdlets loaded.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InitialSessionState parameter\n$option = New-PSRuleOption -InitialSessionState 'Minimal';\n</code></pre> <pre><code># PowerShell: Using the Execution.InitialSessionState hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InitialSessionState' = 'Minimal' };\n</code></pre> <pre><code># PowerShell: Using the InitialSessionState parameter to set YAML\nSet-PSRuleOption -InitialSessionState 'Minimal';\n</code></pre> <pre><code># YAML: Using the execution/initialSessionState property\nexecution:\n  initialSessionState: Minimal\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_INITIALSESSIONSTATE=Minimal\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_INITIALSESSIONSTATE: Minimal\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INITIALSESSIONSTATE\n  value: Minimal\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrestrictscriptsource","title":"Execution.RestrictScriptSource","text":"<p> v3.0.0</p> <p>Configures where to allow PowerShell language features (such as rules and conventions) to run from. In locked down environments, running PowerShell scripts from the workspace may not be allowed. Only run scripts from a trusted source.</p> <p>This option does not affect YAML or JSON based rules and resources.</p> <p>The following script source restrictions are available:</p> <ul> <li><code>Unrestricted</code> - PowerShell language features are allowed from workspace and modules.   This is the default.</li> <li><code>ModuleOnly</code> - PowerShell language features are allowed from loaded modules,   but script files within the workspace are ignored.</li> <li><code>DisablePowerShell</code> - No PowerShell language features are used during PSRule run.   When this mode is used, rules and conventions written in PowerShell will not execute.   Modules that use PowerShell rules and conventions may not work as expected.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RestrictScriptSource parameter\n$option = New-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n</code></pre> <pre><code># PowerShell: Using the Execution.RestrictScriptSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RestrictScriptSource' = 'ModuleOnly' };\n</code></pre> <pre><code># PowerShell: Using the RestrictScriptSource parameter to set YAML\nSet-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n</code></pre> <pre><code># YAML: Using the execution/restrictScriptSource property\nexecution:\n  restrictScriptSource: ModuleOnly\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE=ModuleOnly\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE: ModuleOnly\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE\n  value: ModuleOnly\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleinconclusive","title":"Execution.RuleInconclusive","text":"<p> v2.9.0</p> <p>Determines how to handle rules that generate inconclusive results. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionRuleInconclusive parameter\n$option = New-PSRuleOption -ExecutionRuleInconclusive 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.RuleInconclusive hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleInconclusive' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionRuleInconclusive parameter to set YAML\nSet-PSRuleOption -ExecutionRuleInconclusive 'Error';\n</code></pre> <pre><code># YAML: Using the execution/ruleInconclusive property\nexecution:\n  ruleInconclusive: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEINCONCLUSIVE=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RULEINCONCLUSIVE: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEINCONCLUSIVE\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionsuppressiongroupexpired","title":"Execution.SuppressionGroupExpired","text":"<p> v2.6.0</p> <p>Determines how to handle expired suppression groups. Regardless of the value, an expired suppression group will be ignored. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the SuppressionGroupExpired parameter\n$option = New-PSRuleOption -SuppressionGroupExpired 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.SuppressionGroupExpired hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.SuppressionGroupExpired' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the SuppressionGroupExpired parameter to set YAML\nSet-PSRuleOption -SuppressionGroupExpired 'Error';\n</code></pre> <pre><code># YAML: Using the execution/suppressionGroupExpired property\nexecution:\n  suppressionGroupExpired: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleexcluded","title":"Execution.RuleExcluded","text":"<p> v2.8.0</p> <p>Determines how to handle excluded rules. Regardless of the value, excluded rules are ignored. By default, a rule is excluded silently, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Ignore</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.   This is the default.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionRuleExcluded parameter\n$option = New-PSRuleOption -ExecutionRuleExcluded 'Warn';\n</code></pre> <pre><code># PowerShell: Using the Execution.RuleExcluded hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleExcluded' = 'Warn' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionRuleExcluded parameter to set YAML\nSet-PSRuleOption -ExecutionRuleExcluded 'Warn';\n</code></pre> <pre><code># YAML: Using the execution/ruleExcluded property\nexecution:\n  ruleExcluded: Warn\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEEXCLUDED=Warn\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RULEEXCLUDED: Warn\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEEXCLUDED\n  value: Warn\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrulesuppressed","title":"Execution.RuleSuppressed","text":"<p> v2.8.0</p> <p>Determines how to handle suppressed rules. Regardless of the value, a suppressed rule is ignored. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <pre><code># PowerShell: Using the ExecutionRuleSuppressed parameter\n$option = New-PSRuleOption -ExecutionRuleSuppressed 'Error';\n</code></pre> <pre><code># PowerShell: Using the Execution.RuleSuppressed hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleSuppressed' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionRuleSuppressed parameter to set YAML\nSet-PSRuleOption -ExecutionRuleSuppressed 'Error';\n</code></pre> <pre><code># YAML: Using the execution/ruleSuppressed property\nexecution:\n  ruleSuppressed: Error\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_RULESUPPRESSED=Error\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_RULESUPPRESSED: Error\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULESUPPRESSED\n  value: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionunprocessedobject","title":"Execution.UnprocessedObject","text":"<p> v2.9.0</p> <p>Determines how to report objects that are not processed by any rule. By default, a warning is generated, however this behavior can be modified by this option.</p> <p>The following preferences are available:</p> <ul> <li><code>None</code> (0) - No preference.   Inherits the default of <code>Warn</code>.</li> <li><code>Ignore</code> (1) - Continue to execute silently.</li> <li><code>Warn</code> (2) - Continue to execute but log a warning.   This is the default.</li> <li><code>Error</code> (3) - Abort and throw an error.</li> <li><code>Debug</code> (4) - Continue to execute but log a debug message.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ExecutionUnprocessedObject parameter\n$option = New-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n</code></pre> <pre><code># PowerShell: Using the Execution.UnprocessedObject hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.UnprocessedObject' = 'Ignore' };\n</code></pre> <pre><code># PowerShell: Using the ExecutionUnprocessedObject parameter to set YAML\nSet-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n</code></pre> <pre><code># YAML: Using the execution/unprocessedObject property\nexecution:\n  unprocessedObject: Ignore\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_EXECUTION_UNPROCESSEDOBJECT: Ignore\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_UNPROCESSEDOBJECT\n  value: Ignore\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includemodule","title":"Include.Module","text":"<p>Automatically include rules and resources from the specified module. To automatically import and include a module specify the module by name. The module must already be installed on the system.</p> <p>When <code>$PSModuleAutoLoadingPreference</code> is set to a value other then <code>All</code> the module must be imported.</p> <p>This option is equivalent to using the <code>-Module</code> parameter on PSRule cmdlets, with the following addition:</p> <ul> <li>Modules specified with <code>Include.Module</code> are combined with <code>-Module</code>.   Both sets of modules will be imported and used using execution.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the IncludeModule parameter\n$option = New-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n</code></pre> <pre><code># PowerShell: Using the Include.Module hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Module' = 'TestModule1', 'TestModule2' };\n</code></pre> <pre><code># PowerShell: Using the IncludeModule parameter to set YAML\nSet-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n</code></pre> <pre><code># YAML: Using the include/module property\ninclude:\n  module:\n  - TestModule1\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INCLUDE_MODULE=TestModule1;TestModule2\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INCLUDE_MODULE: TestModule1;TestModule2\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_MODULE\n  value: TestModule1;TestModule2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includepath","title":"Include.Path","text":"<p>Automatically include rules and resources from the specified path. By default, <code>.ps-rule/</code> is included.</p> <p>This option is equivalent to using the <code>-Path</code> parameter on PSRule cmdlets, with the following additions:</p> <ul> <li>Paths specified with <code>Include.Path</code> are combined with <code>-Path</code>.   Both sets of paths will be imported and used using execution.</li> <li>The <code>Include.Path</code> option defaults to <code>.ps-rule/</code>.   To override this default, specify one or more alternative paths or an empty array.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the IncludePath parameter\n$option = New-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n</code></pre> <pre><code># PowerShell: Using the Include.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Path' = '.ps-rule/', 'custom-rules/' };\n</code></pre> <pre><code># PowerShell: Using the IncludePath parameter to set YAML\nSet-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n</code></pre> <pre><code># YAML: Using the include/path property\ninclude:\n  path:\n  - custom-rules/\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INCLUDE_PATH=.ps-rule/;custom-rules/\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INCLUDE_PATH: .ps-rule/;custom-rules/\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_PATH\n  value: .ps-rule/;custom-rules/\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputformat","title":"Input.Format","text":"<p>Configures the input format for when a string is passed in as a target object. This option determines if the target object is deserialized into an alternative form.</p> <p>Use this option with <code>Assert-PSRule</code>, <code>Invoke-PSRule</code> or <code>Test-PSRuleTarget</code>. Set this option to either <code>Yaml</code>, <code>Json</code>, <code>Markdown</code>, <code>PowerShellData</code> to deserialize as a specific format. The <code>-Format</code> parameter will override any value set in configuration.</p> <p>When the <code>-InputObject</code> parameter or pipeline input is used, strings are treated as plain text by default. <code>FileInfo</code> objects for supported file formats will be deserialized based on file extension.</p> <p>When the <code>-InputPath</code> parameter is used, supported file formats will be deserialized based on file extension. The <code>-InputPath</code> parameter can be used with a file path or URL.</p> <p>The following formats are available:</p> <ul> <li>None - Treat strings as plain text and do not deserialize files.</li> <li>Yaml - Deserialize as one or more YAML objects.</li> <li>Json - Deserialize as one or more JSON objects.</li> <li>Markdown - Deserialize as a markdown object.</li> <li>PowerShellData - Deserialize as a PowerShell data object.</li> <li>File - Files are not deserialized.</li> <li>Detect - Detect format based on file extension. This is the default.</li> </ul> <p>If the <code>Detect</code> format is used, the file extension will be used to automatically detect the format. When the file extension can not be determined <code>Detect</code> is the same as <code>None</code>.</p> <p>The <code>Markdown</code> format does not parse the whole markdown document. Specifically this format deserializes YAML front matter from the top of the document if any exists.</p> <p>The <code>File</code> format does not deserialize file contents. Each file is returned as an object. Files within <code>.git</code> sub-directories are ignored. Path specs specified in <code>.gitignore</code> directly in the current working path are ignored. A <code>RepositoryInfo</code> object is generated if the current working path if a <code>.git</code> sub-directory is present. Additionally, PSRule performs automatic type binding for file objects, using the extension as the type. When files have no extension the whole file name is used.</p> <p>Detect uses the following file extensions:</p> <ul> <li>Yaml - <code>.yaml</code> or <code>.yml</code></li> <li>Json - <code>.json</code> or <code>.jsonc</code></li> <li>Markdown - <code>.md</code> or <code>.markdown</code></li> <li>PowerShellData - <code>.psd1</code></li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Format parameter\n$option = New-PSRuleOption -Format Yaml;\n</code></pre> <pre><code># PowerShell: Using the Input.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.Format' = 'Yaml' };\n</code></pre> <pre><code># PowerShell: Using the Format parameter to set YAML\nSet-PSRuleOption -Format Yaml;\n</code></pre> <pre><code># YAML: Using the input/format property\ninput:\n  format: Yaml\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_FORMAT=Yaml\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_FORMAT: Yaml\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_FORMAT\n  value: Yaml\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoregitpath","title":"Input.IgnoreGitPath","text":"<p>When reading files from an input path, files within the <code>.git</code> sub-directory are ignored by default. Files stored within the <code>.git</code> sub-directory are system repository files used by git. To read files stored within the <code>.git</code> path, set this option to <code>$False</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreGitPath parameter\n$option = New-PSRuleOption -InputIgnoreGitPath $False;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreGitPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreGitPath' = $False };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreGitPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreGitPath $False;\n</code></pre> <pre><code># YAML: Using the input/ignoreGitPath property\ninput:\n  ignoreGitPath: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREGITPATH=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREGITPATH: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREGITPATH\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreobjectsource","title":"Input.IgnoreObjectSource","text":"<p>By default, objects read from file using <code>inputPath</code> will be skipped if the file path has been ignored. When set to true, additionally objects with a source path that has been ignored will be skipped. This will include <code>FileInfo</code> objects, and objects with a source set using the <code>_PSRule.source</code> property.</p> <p>File paths to ignore are set by <code>Input.PathIgnore</code>, <code>Input.IgnoreGitPath</code>, and <code>Input.IgnoreRepositoryCommon</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreObjectSource parameter\n$option = New-PSRuleOption -InputIgnoreObjectSource $True;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreObjectSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreObjectSource' = $True };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreObjectSource parameter to set YAML\nSet-PSRuleOption -InputIgnoreObjectSource $True;\n</code></pre> <pre><code># YAML: Using the input/ignoreObjectSource property\ninput:\n  ignoreObjectSource: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREOBJECTSOURCE=true\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREOBJECTSOURCE: true\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREOBJECTSOURCE\n  value: true\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignorerepositorycommon","title":"Input.IgnoreRepositoryCommon","text":"<p>When reading files from an input path, files are discovered recursively. A number of files are commonly found within a private and open-source repositories. In many cases these files are of no interest for analysis and should be ignored by rules. PSRule will ignore the following files by default:</p> <ul> <li><code>README.md</code></li> <li><code>.DS_Store</code></li> <li><code>.gitignore</code></li> <li><code>.gitattributes</code></li> <li><code>.gitmodules</code></li> <li><code>LICENSE</code></li> <li><code>LICENSE.txt</code></li> <li><code>CODE_OF_CONDUCT.md</code></li> <li><code>CONTRIBUTING.md</code></li> <li><code>SECURITY.md</code></li> <li><code>SUPPORT.md</code></li> <li><code>.vscode/*.json</code></li> <li><code>.vscode/*.code-snippets</code></li> <li><code>.github/**/*.md</code></li> <li><code>.github/CODEOWNERS</code></li> <li><code>.pipelines/**/*.yml</code></li> <li><code>.pipelines/**/*.yaml</code></li> <li><code>.azure-pipelines/**/*.yml</code></li> <li><code>.azure-pipelines/**/*.yaml</code></li> <li><code>.azuredevops/*.md</code></li> </ul> <p>To include these files, set this option to <code>$False</code>. This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreRepositoryCommon parameter\n$option = New-PSRuleOption -InputIgnoreRepositoryCommon $False;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreRepositoryCommon hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreRepositoryCommon' = $False };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreRepositoryCommon parameter to set YAML\nSet-PSRuleOption -InputIgnoreRepositoryCommon $False;\n</code></pre> <pre><code># YAML: Using the input/ignoreRepositoryCommon property\ninput:\n  ignoreRepositoryCommon: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREREPOSITORYCOMMON=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREREPOSITORYCOMMON: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREREPOSITORYCOMMON\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreunchangedpath","title":"Input.IgnoreUnchangedPath","text":"<p> v2.5.0</p> <p>By default, PSRule will process all files within an input path. For large repositories, this can result in a large number of files being processed. Additionally, for a pull request you may only be interested in files that have changed.</p> <p>When set to <code>true</code>, files that have not changed will be ignored. This option can be specified using:</p> <pre><code># PowerShell: Using the InputIgnoreUnchangedPath parameter\n$option = New-PSRuleOption -InputIgnoreUnchangedPath $True;\n</code></pre> <pre><code># PowerShell: Using the Input.IgnoreUnchangedPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreUnchangedPath' = $True };\n</code></pre> <pre><code># PowerShell: Using the InputIgnoreUnchangedPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreUnchangedPath $True;\n</code></pre> <pre><code># YAML: Using the input/ignoreUnchangedPath property\ninput:\n  ignoreUnchangedPath: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREUNCHANGEDPATH=true\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREUNCHANGEDPATH\n  value: true\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputobjectpath","title":"Input.ObjectPath","text":"<p>The object path to a property to use instead of the pipeline object.</p> <p>By default, PSRule processes objects passed from the pipeline against selected rules. When this option is set, instead of evaluating the pipeline object, PSRule looks for a property of the pipeline object specified by <code>ObjectPath</code> and uses that instead. If the property specified by <code>ObjectPath</code> is a collection/ array, then each item is evaluated separately.</p> <p>If the property specified by <code>ObjectPath</code> does not exist, PSRule skips the object.</p> <p>When using <code>Invoke-PSRule</code>, <code>Test-PSRuleTarget</code>, and <code>Assert-PSRule</code> the <code>-ObjectPath</code> parameter will override any value set in configuration.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the ObjectPath parameter\n$option = New-PSRuleOption -ObjectPath 'items';\n</code></pre> <pre><code># PowerShell: Using the Input.ObjectPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.ObjectPath' = 'items' };\n</code></pre> <pre><code># PowerShell: Using the ObjectPath parameter to set YAML\nSet-PSRuleOption -ObjectPath 'items';\n</code></pre> <pre><code># YAML: Using the input/objectPath property\ninput:\n  objectPath: items\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_OBJECTPATH=items\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_OBJECTPATH: items\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_OBJECTPATH\n  value: items\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputpathignore","title":"Input.PathIgnore","text":"<p>Ignores input files that match the path spec when using <code>-InputPath</code>. If specified, files that match the path spec will not be processed. By default, all files are processed.</p> <p>For example, ignoring file extensions:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude files with these extensions\n  - '*.md'\n  - '*.png'\n  # Exclude specific configuration files\n  - 'bicepconfig.json'\n</code></pre> <p>For example, ignoring all files with exceptions:</p> <pre><code>input:\n  pathIgnore:\n  # Exclude all files\n  - '*'\n  # Only process deploy.bicep files\n  - '!**/deploy.bicep'\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputPathIgnore parameter\n$option = New-PSRuleOption -InputPathIgnore '*.Designer.cs';\n</code></pre> <pre><code># PowerShell: Using the Input.PathIgnore hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.PathIgnore' = '*.Designer.cs' };\n</code></pre> <pre><code># PowerShell: Using the InputPathIgnore parameter to set YAML\nSet-PSRuleOption -InputPathIgnore '*.Designer.cs';\n</code></pre> <pre><code># YAML: Using the input/pathIgnore property\ninput:\n  pathIgnore:\n  - '*.Designer.cs'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_PATHIGNORE=*.Designer.cs\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_PATHIGNORE: '*.Designer.cs'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_PATHIGNORE\n  value: '*.Designer.cs'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputtargettype","title":"Input.TargetType","text":"<p>Filters input objects by TargetType.</p> <p>If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This option is not case-sensitive.</p> <p>By default, all objects are processed.</p> <p>To change the field TargetType is bound to set the <code>Binding.TargetType</code> option.</p> <p>When using <code>Invoke-PSRule</code>, <code>Test-PSRuleTarget</code>, and <code>Assert-PSRule</code> the <code>-TargetType</code> parameter will override any value set in configuration.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the InputTargetType parameter\n$option = New-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n</code></pre> <pre><code># PowerShell: Using the Input.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.TargetType' = 'virtualMachine', 'virtualNetwork' };\n</code></pre> <pre><code># PowerShell: Using the InputTargetType parameter to set YAML\nSet-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n</code></pre> <pre><code># YAML: Using the input/targetType property\ninput:\n  targetType:\n  - virtualMachine\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_INPUT_TARGETTYPE=virtualMachine;virtualNetwork\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_INPUT_TARGETTYPE: virtualMachine;virtualNetwork\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_TARGETTYPE\n  value: virtualMachine;virtualNetwork\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitdebug","title":"Logging.LimitDebug","text":"<p>Limits debug messages to a list of named debug scopes.</p> <p>When using the <code>-Debug</code> switch or preference variable, by default PSRule cmdlets log all debug output. When using debug output for debugging a specific rule, it may be helpful to limit debug message to a specific rule.</p> <p>To identify a rule to include in debug output use the rule name.</p> <p>The following built-in scopes exist in addition to rule names:</p> <ul> <li><code>[Discovery.Source]</code> - Discovery messages for <code>.Rule.ps1</code> files and rule modules.</li> <li><code>[Discovery.Rule]</code> - Discovery messages for individual rules within <code>.Rule.ps1</code> files.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingLimitDebug parameter\n$option = New-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n</code></pre> <pre><code># PowerShell: Using the Logging.LimitDebug hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitDebug' = Rule1, Rule2 };\n</code></pre> <pre><code># PowerShell: Using the LoggingLimitDebug parameter to set YAML\nSet-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n</code></pre> <pre><code># YAML: Using the logging/limitDebug property\nlogging:\n  limitDebug:\n  - Rule1\n  - Rule2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitverbose","title":"Logging.LimitVerbose","text":"<p>Limits verbose messages to a list of named verbose scopes.</p> <p>When using the <code>-Verbose</code> switch or preference variable, by default PSRule cmdlets log all verbose output. When using verbose output for troubleshooting a specific rule, it may be helpful to limit verbose messages to a specific rule.</p> <p>To identify a rule to include in verbose output use the rule name.</p> <p>The following built-in scopes exist in addition to rule names:</p> <ul> <li><code>[Discovery.Source]</code> - Discovery messages for <code>.Rule.ps1</code> files and rule modules.</li> <li><code>[Discovery.Rule]</code> - Discovery messages for individual rules within <code>.Rule.ps1</code> files.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingLimitVerbose parameter\n$option = New-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n</code></pre> <pre><code># PowerShell: Using the Logging.LimitVerbose hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitVerbose' = Rule1, Rule2 };\n</code></pre> <pre><code># PowerShell: Using the LoggingLimitVerbose parameter to set YAML\nSet-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n</code></pre> <pre><code># YAML: Using the logging/limitVerbose property\nlogging:\n  limitVerbose:\n  - Rule1\n  - Rule2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulefail","title":"Logging.RuleFail","text":"<p>When an object fails a rule condition the results are written to output as a structured object marked with the outcome of Fail. If the rule executed successfully regardless of outcome no other informational messages are shown by default.</p> <p>In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages or abort the CI process if one or more Fail outcomes are returned.</p> <p>By settings this option, error, warning or information messages will be generated for each rule fail outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).</p> <p>The following streams available:</p> <ul> <li>None</li> <li>Error</li> <li>Warning</li> <li>Information</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingRuleFail parameter\n$option = New-PSRuleOption -LoggingRuleFail Error;\n</code></pre> <pre><code># PowerShell: Using the Logging.RuleFail hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RuleFail' = 'Error' };\n</code></pre> <pre><code># PowerShell: Using the LoggingRuleFail parameter to set YAML\nSet-PSRuleOption -LoggingRuleFail Error;\n</code></pre> <pre><code># YAML: Using the logging/ruleFail property\nlogging:\n  ruleFail: Error\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulepass","title":"Logging.RulePass","text":"<p>When an object passes a rule condition the results are written to output as a structured object marked with the outcome of Pass. If the rule executed successfully regardless of outcome no other informational messages are shown by default.</p> <p>In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages.</p> <p>By settings this option, error, warning or information messages will be generated for each rule pass outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).</p> <p>The following streams available:</p> <ul> <li>None</li> <li>Error</li> <li>Warning</li> <li>Information</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the LoggingRulePass parameter\n$option = New-PSRuleOption -LoggingRulePass Information;\n</code></pre> <pre><code># PowerShell: Using the Logging.RulePass hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RulePass' = 'Information' };\n</code></pre> <pre><code># PowerShell: Using the LoggingRulePass parameter to set YAML\nSet-PSRuleOption -LoggingRulePass Information;\n</code></pre> <pre><code># YAML: Using the logging/rulePass property\nlogging:\n  rulePass: Information\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputas","title":"Output.As","text":"<p>Configures the type of results to produce.</p> <p>This option only applies to <code>Invoke-PSRule</code> and <code>Assert-PSRule</code>. <code>Invoke-PSRule</code> and <code>Assert-PSRule</code> also include a <code>-As</code> parameter to set this option at runtime. If specified, the <code>-As</code> parameter take precedence, over this option.</p> <p>The following options are available:</p> <ul> <li>Detail - Return a record per rule per object.</li> <li>Summary - Return summary results.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputAs parameter\n$option = New-PSRuleOption -OutputAs Summary;\n</code></pre> <pre><code># PowerShell: Using the Output.As hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.As' = 'Summary' };\n</code></pre> <pre><code># PowerShell: Using the OutputAs parameter to set YAML\nSet-PSRuleOption -OutputAs Summary;\n</code></pre> <pre><code># YAML: Using the output/as property\noutput:\n  as: Summary\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_AS=Summary\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_AS: Summary\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_AS\n  value: Summary\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputbanner","title":"Output.Banner","text":"<p>The information displayed for PSRule banner. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <p>The following information can be shown or hidden by configuring this option.</p> <ul> <li><code>Title</code> (1) - Shows the PSRule title ASCII text.</li> <li><code>Source</code> (2) - Shows rules module versions used in this run.</li> <li><code>SupportLinks</code> (4) - Shows supporting links for PSRule and rules modules.</li> <li><code>RepositoryInfo</code> (8) - Show information about the repository where PSRule is being run from.</li> </ul> <p>Additionally the following rollup options exist:</p> <ul> <li><code>Default</code> - Shows <code>Title</code>, <code>Source</code>, <code>SupportLinks</code>, <code>RepositoryInfo</code>. This is the default option.</li> <li><code>Minimal</code> - Shows <code>Source</code>.</li> </ul> <p>This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example <code>6</code> would show <code>Source</code>, and <code>SupportLinks</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputBanner parameter\n$option = New-PSRuleOption -OutputBanner Minimal;\n</code></pre> <pre><code># PowerShell: Using the Output.Banner hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Banner' = 'Minimal' };\n</code></pre> <pre><code># PowerShell: Using the OutputBanner parameter to set YAML\nSet-PSRuleOption -OutputBanner Minimal;\n</code></pre> <pre><code># YAML: Using the output/banner property\noutput:\n  banner: Minimal\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_BANNER=Minimal\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_BANNER: Minimal\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_BANNER\n  value: Minimal\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputculture","title":"Output.Culture","text":"<p>Specified the name of one or more cultures to use for generating output. When multiple cultures are specified, the first matching culture will be used. If a culture is not specified, PSRule will use the current PowerShell culture.</p> <p>PSRule cmdlets also include a <code>-Culture</code> parameter to set this option at runtime. If specified, the <code>-Culture</code> parameter take precedence, over this option.</p> <p>To get a list of cultures use the <code>Get-Culture -ListAvailable</code> cmdlet.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputCulture parameter\n$option = New-PSRuleOption -OutputCulture 'en-AU';\n</code></pre> <pre><code># PowerShell: Using the Output.Culture hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Culture' = 'en-AU' };\n</code></pre> <pre><code># PowerShell: Using the OutputCulture parameter to set YAML\nSet-PSRuleOption -OutputCulture 'en-AU', 'en-US';\n</code></pre> <pre><code># YAML: Using the output/culture property\noutput:\n  culture: [ 'en-AU', 'en-US' ]\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_CULTURE=en-AU;en-US\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_CULTURE: en-AU;en-US\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_CULTURE\n  value: en-AU;en-US\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputencoding","title":"Output.Encoding","text":"<p>Configures the encoding used when output is written to file. This option has no affect when <code>Output.Path</code> is not set.</p> <p>The following encoding options are available:</p> <ul> <li>Default</li> <li>UTF-8</li> <li>UTF-7</li> <li>Unicode</li> <li>UTF-32</li> <li>ASCII</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputEncoding parameter\n$option = New-PSRuleOption -OutputEncoding UTF8;\n</code></pre> <pre><code># PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Encoding' = 'UTF8' };\n</code></pre> <pre><code># PowerShell: Using the OutputEncoding parameter to set YAML\nSet-PSRuleOption -OutputEncoding UTF8;\n</code></pre> <pre><code># YAML: Using the output/encoding property\noutput:\n  encoding: UTF8\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_ENCODING=UTF8\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_ENCODING: UTF8\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_ENCODING\n  value: UTF8\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputfooter","title":"Output.Footer","text":"<p>The information displayed for PSRule footer. This option is only applicable when using <code>Assert-PSRule</code> cmdlet.</p> <p>The following information can be shown or hidden by configuring this option.</p> <ul> <li><code>RuleCount</code> (1) - Shows a summary of rules processed.</li> <li><code>RunInfo</code> (2) - Shows information about the run.</li> <li><code>OutputFile</code> (4) - Shows information about the output file if an output path is set.</li> </ul> <p>Additionally the following rollup options exist:</p> <ul> <li><code>Default</code> - Shows <code>RuleCount</code>, <code>RunInfo</code>, and <code>OutputFile</code>. This is the default option.</li> </ul> <p>This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example <code>3</code> would show <code>RunInfo</code>, and <code>RuleCount</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputFooter parameter\n$option = New-PSRuleOption -OutputFooter RuleCount;\n</code></pre> <pre><code># PowerShell: Using the Output.Footer hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Footer' = 'RuleCount' };\n</code></pre> <pre><code># PowerShell: Using the OutputFooter parameter to set YAML\nSet-PSRuleOption -OutputFooter RuleCount;\n</code></pre> <pre><code># YAML: Using the output/footer property\noutput:\n  footer: RuleCount\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_FOOTER=RuleCount\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_FOOTER: RuleCount\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FOOTER\n  value: RuleCount\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputformat","title":"Output.Format","text":"<p>Configures the format that results will be presented in. This option applies to <code>Invoke-PSRule</code>, <code>Assert-PSRule</code>, <code>Get-PSRule</code> and <code>Get-PSRuleBaseline</code>. This options is ignored by other cmdlets.</p> <p>The following format options are available:</p> <ul> <li>None - Output is presented as an object using PowerShell defaults.   This is the default.</li> <li>Yaml - Output is serialized as YAML.</li> <li>Json - Output is serialized as JSON.</li> <li>Markdown - Output is serialized as Markdown.</li> <li>NUnit3 - Output is serialized as NUnit3 (XML).</li> <li>Csv - Output is serialized as a comma-separated values (CSV).<ul> <li>The following columns are included for <code>Detail</code> output: RuleName, TargetName, TargetType, Outcome, OutcomeReason, Synopsis, Recommendation</li> <li>The following columns are included for <code>Summary</code> output: RuleName, Pass, Fail, Outcome, Synopsis, Recommendation</li> </ul> </li> <li>Wide -  Output is presented using the wide table format, which includes reason and wraps columns.</li> <li>Sarif - Output is serialized as SARIF.</li> </ul> <p>The Wide format is ignored by <code>Assert-PSRule</code>. <code>Get-PSRule</code> only accepts <code>None</code>, <code>Wide</code>, <code>Yaml</code> and <code>Json</code>. Usage of other formats are treated as <code>None</code>.</p> <p>The <code>Get-PSRuleBaseline</code> cmdlet only accepts <code>None</code> or <code>Yaml</code>. The <code>Export-PSRuleBaseline</code> cmdlet only accepts <code>Yaml</code>.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputFormat parameter\n$option = New-PSRuleOption -OutputFormat Yaml;\n</code></pre> <pre><code># PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Format' = 'Yaml' };\n</code></pre> <pre><code># PowerShell: Using the OutputFormat parameter to set YAML\nSet-PSRuleOption -OutputFormat Yaml;\n</code></pre> <pre><code># YAML: Using the output/format property\noutput:\n  format: Yaml\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_FORMAT=Yaml\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_FORMAT: Yaml\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FORMAT\n  value: Yaml\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputoutcome","title":"Output.Outcome","text":"<p>Filters output to include results with the specified outcome. The following outcome options are available:</p> <ul> <li><code>None</code> (0) - Results for rules that did not get processed are returned.   This include rules that have been suppressed or were not run against a target object.</li> <li><code>Fail</code> (1) - Results for rules that failed are returned.</li> <li><code>Pass</code> (2)  - Results for rules that passed are returned.</li> <li><code>Error</code> (4) - Results for rules that raised an error are returned.</li> </ul> <p>Additionally the following rollup options exist:</p> <ul> <li><code>Processed</code> - Results for rules with the <code>Fail</code>, <code>Pass</code>, or <code>Error</code> outcome. This is the default option.</li> <li><code>Problem</code> - Results for rules with the <code>Fail</code>, or <code>Error</code> outcome.</li> <li><code>All</code> - All results for rules are returned.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputOutcome parameter\n$option = New-PSRuleOption -OutputOutcome Fail;\n</code></pre> <pre><code># PowerShell: Using the Output.Outcome hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Outcome' = 'Fail' };\n</code></pre> <pre><code># PowerShell: Using the OutputOutcome parameter to set YAML\nSet-PSRuleOption -OutputOutcome Fail;\n</code></pre> <pre><code># YAML: Using the output/outcome property\noutput:\n  outcome: 'Fail'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_OUTCOME=Fail\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_OUTCOME: Fail\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_OUTCOME\n  value: Fail\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputpath","title":"Output.Path","text":"<p>Specifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.</p> <p>This option only applies to <code>Invoke-PSRule</code>. <code>Invoke-PSRule</code> also includes a parameter <code>-OutputPath</code> to set this option at runtime. If specified, the <code>-OutputPath</code> parameter take precedence, over this option.</p> <p>Syntax:</p> <pre><code>output:\n  path: string\n</code></pre> <p>Default:</p> <pre><code>output:\n  path: null\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputPath parameter\n$option = New-PSRuleOption -OutputPath 'out/results.yaml';\n</code></pre> <pre><code># PowerShell: Using the Output.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Path' = 'out/results.yaml' };\n</code></pre> <pre><code># PowerShell: Using the OutputPath parameter to set YAML\nSet-PSRuleOption -OutputPath 'out/results.yaml';\n</code></pre> <pre><code># YAML: Using the output/path property\noutput:\n  path: 'out/results.yaml'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_PATH=out/results.yaml\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_PATH: out/results.yaml\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_PATH\n  value: out/results.yaml\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputsarifproblemsonly","title":"Output.SarifProblemsOnly","text":"<p>Determines if SARIF output only includes rules with fail or error outcomes. By default, only rules with fail or error outcomes are included for compatibility with external tools. To include rules with pass outcomes, set this option to <code>false</code>. This option only applies when the output format is <code>Sarif</code>.</p> <p>Syntax:</p> <pre><code>output:\n  sarifProblemsOnly: boolean\n</code></pre> <p>Default:</p> <pre><code>output:\n  sarifProblemsOnly: true\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputSarifProblemsOnly parameter\n$option = New-PSRuleOption -OutputSarifProblemsOnly $False;\n</code></pre> <pre><code># PowerShell: Using the Output.SarifProblemsOnly hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.SarifProblemsOnly' = $False };\n</code></pre> <pre><code># PowerShell: Using the OutputSarifProblemsOnly parameter to set YAML\nSet-PSRuleOption -OutputSarifProblemsOnly $False;\n</code></pre> <pre><code># YAML: Using the output/sarifProblemsOnly property\noutput:\n  sarifProblemsOnly: false\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_SARIFPROBLEMSONLY=false\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_SARIFPROBLEMSONLY: false\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_SARIFPROBLEMSONLY\n  value: false\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputstyle","title":"Output.Style","text":"<p>Configures the style that results will be presented in.</p> <p>This option only applies to output generated from <code>Assert-PSRule</code>. <code>Assert-PSRule</code> also include a parameter <code>-Style</code> to set this option at runtime. If specified, the <code>-Style</code> parameter takes precedence, over this option.</p> <p>The following styles are available:</p> <ul> <li><code>Client</code> - Output is written to the host directly in green/ red to indicate outcome.</li> <li><code>Plain</code> - Output is written as an unformatted string. This option can be redirected to a file.</li> <li><code>AzurePipelines</code> - Output is written for integration Azure Pipelines.</li> <li><code>GitHubActions</code> - Output is written for integration GitHub Actions.</li> <li><code>VisualStudioCode</code> - Output is written for integration with Visual Studio Code.</li> <li><code>Detect</code> - Output style will be detected by checking the environment variables. This is the default.</li> </ul> <p>Detect uses the following logic:</p> <ol> <li>If the <code>TF_BUILD</code> environment variable is set to <code>true</code>, <code>AzurePipelines</code> will be used.</li> <li>If the <code>GITHUB_ACTIONS</code> environment variable is set to <code>true</code>, <code>GitHubActions</code> will be used.</li> <li>If the <code>TERM_PROGRAM</code> environment variable is set to <code>vscode</code>, <code>VisualStudioCode</code> will be used.</li> <li>Use <code>Client</code>.</li> </ol> <p>Syntax:</p> <pre><code>output:\n  style: string\n</code></pre> <p>Default:</p> <pre><code>output:\n  style: Detect\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputStyle parameter\n$option = New-PSRuleOption -OutputStyle AzurePipelines;\n</code></pre> <pre><code># PowerShell: Using the Output.Style hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Style' = 'AzurePipelines' };\n</code></pre> <pre><code># PowerShell: Using the OutputStyle parameter to set YAML\nSet-PSRuleOption -OutputFormat AzurePipelines;\n</code></pre> <pre><code># YAML: Using the output/style property\noutput:\n  style: AzurePipelines\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=AzurePipelines\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_STYLE: AzurePipelines\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n  value: AzurePipelines\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjobsummarypath","title":"Output.JobSummaryPath","text":"<p> v2.6.0</p> <p>Configures the file path a job summary will be written to when using <code>Assert-PSRule</code>. A job summary is a markdown file that summarizes the results of a job. When not specified, a job summary will not be generated.</p> <p>Syntax:</p> <pre><code>output:\n  jobSummaryPath: string\n</code></pre> <p>Default:</p> <pre><code>output:\n  jobSummaryPath: null\n</code></pre> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputJobSummaryPath parameter\n$option = New-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n</code></pre> <pre><code># PowerShell: Using the Output.JobSummaryPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JobSummaryPath' = 'reports/summary.md' };\n</code></pre> <pre><code># PowerShell: Using the OutputJobSummaryPath parameter to set YAML\nSet-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n</code></pre> <pre><code># YAML: Using the output/jobSummaryPath property\noutput:\n  jobSummaryPath: 'reports/summary.md'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_JOBSUMMARYPATH='reports/summary.md'\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JOBSUMMARYPATH = 'reports/summary.md';\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_JOBSUMMARYPATH: reports/summary.md\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JOBSUMMARYPATH\n  value: reports/summary.md\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjsonindent","title":"Output.JsonIndent","text":"<p>Configures the number of spaces to indent JSON properties and elements. The default number of spaces is 0.</p> <p>This option applies to output generated from <code>-OutputFormat Json</code> for <code>Get-PSRule</code> and <code>Invoke-PSRule</code>. This option also applies to output generated from <code>-OutputPath</code> for <code>Assert-PSRule</code>.</p> <p>The range of indentation accepts a minimum of 0 (machine first) spaces and a maximum of 4 spaces.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the OutputJsonIndent parameter\n$option = New-PSRuleOption -OutputJsonIndent 2;\n</code></pre> <pre><code># PowerShell: Using the Output.JsonIndent hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JsonIndent' = 2 };\n</code></pre> <pre><code># PowerShell: Using the OutputJsonIndent parameter to set YAML\nSet-PSRuleOption -OutputJsonIndent 2;\n</code></pre> <pre><code># YAML: Using the output/jsonIndent property\noutput:\n  jsonIndent: 2\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_OUTPUT_JSONINDENT=2\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JSONINDENT = 2;\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_OUTPUT_JSONINDENT: 2\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JSONINDENT\n  value: 2\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositorybaseref","title":"Repository.BaseRef","text":"<p>This option is used for specify the base branch for pull requests. When evaluating changes files only PSRule uses this option for comparison with the current branch. By default, the base ref is detected from environment variables set by the build system.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RepositoryBaseRef parameter\n$option = New-PSRuleOption -RepositoryBaseRef 'main';\n</code></pre> <pre><code># PowerShell: Using the Repository.BaseRef hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.BaseRef' = 'main' };\n</code></pre> <pre><code># PowerShell: Using the RepositoryBaseRef parameter to set YAML\nSet-PSRuleOption -RepositoryBaseRef 'main';\n</code></pre> <pre><code># YAML: Using the repository/baseRef property\nrepository:\n  baseRef: main\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_REPOSITORY_BASEREF='main'\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_BASEREF = 'main';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositoryurl","title":"Repository.Url","text":"<p>This option can be configured to set the repository URL reported in output. By default, the repository URL is detected from environment variables set by the build system.</p> <ul> <li>In GitHub Actions, the repository URL is detected from the <code>GITHUB_REPOSITORY</code> environment variable.</li> <li>In Azure Pipelines, the repository URL is detected from the <code>BUILD_REPOSITORY_URI</code> environment variable.</li> </ul> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RepositoryUrl parameter\n$option = New-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n</code></pre> <pre><code># PowerShell: Using the Repository.Url hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.Url' = 'https://github.com/microsoft/PSRule' };\n</code></pre> <pre><code># PowerShell: Using the RepositoryUrl parameter to set YAML\nSet-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n</code></pre> <pre><code># YAML: Using the repository/url property\nrepository:\n  url: 'https://github.com/microsoft/PSRule'\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_REPOSITORY_URL='https://github.com/microsoft/PSRule'\n</code></pre> <pre><code># PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_URL = 'https://github.com/microsoft/PSRule';\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#requires","title":"Requires","text":"<p>Specifies module version constraints for running PSRule. When set PSRule will error if a module version is used that does not satisfy the requirements. The format for version constraints are the same as the <code>Version</code> assertion method. See [about_PSRule_Assert] for more information.</p> <p>Module version constraints a not enforced prior to PSRule v0.19.0.</p> <p>The version constraint for a rule module is enforced when the module is included with <code>-Module</code>. A version constraint does not require a rule module to be included. Use the <code>Include.Module</code> option to automatically include a rule module.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Requires.module hashtable key\n$option = New-PSRuleOption -Option @{ 'Requires.PSRule' = '&gt;=1.0.0' };\n</code></pre> <pre><code># YAML: Using the requires property\nrequires:\n  PSRule: '&gt;=1.0.0'                 # Require v1.0.0 or greater.\n  PSRule.Rules.Azure: '&gt;=1.0.0'     # Require v1.0.0 or greater.\n  PSRule.Rules.CAF: '@pre &gt;=0.1.0'  # Require stable or pre-releases v0.1.0 or greater.\n</code></pre> <p>This option can be configured using environment variables. To specify a module version constraint, prefix the module name with <code>PSRULE_REQUIRES_</code>. When the module name includes a dot (<code>.</code>) use an underscore (<code>_</code>) instead.</p> <pre><code># Bash: Using environment variable\nexport PSRULE_REQUIRES_PSRULE='&gt;=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_AZURE='&gt;=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_CAF='@pre &gt;=0.1.0'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_REQUIRES_PSRULE: '&gt;=1.0.0'\n  PSRULE_REQUIRES_PSRULE_RULES_AZURE: '&gt;=1.0.0'\n  PSRULE_REQUIRES_PSRULE_RULES_CAF: '@pre &gt;=0.1.0'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_REQUIRES_PSRULE\n  value: '&gt;=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_AZURE\n  value: '&gt;=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_CAF\n  value: '@pre &gt;=0.1.0'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#rulebaseline","title":"Rule.Baseline","text":"<p>The name of a default baseline to use for the module. Currently this option can only be set within a module configuration resource.</p> <p>For example:</p> <pre><code>---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n  name: Enterprise.Rules\nspec:\n  rule:\n    baseline: Enterprise.Baseline1\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleinclude","title":"Rule.Include","text":"<p>The name of specific rules to evaluate. If this option is not specified all rules in search paths will be evaluated.</p> <p>This option can be overridden at runtime by using the <code>-Name</code> cmdlet parameter.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Rule.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Include' = 'Rule1','Rule2' };\n</code></pre> <pre><code># YAML: Using the rule/include property\nrule:\n  include:\n  - Rule1\n  - Rule2\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_RULE_INCLUDE='Rule1;Rule2'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_RULE_INCLUDE: 'Rule1;Rule2'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDE\n  value: 'Rule1;Rule2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleincludelocal","title":"Rule.IncludeLocal","text":"<p>Automatically include all local rules in the search path unless they have been explicitly excluded. This option will include local rules even when they do not match <code>Rule.Include</code> or <code>Rule.Tag</code> filters. By default, local rules will be filtered with <code>Rule.Include</code> and <code>Rule.Tag</code> filters.</p> <p>This option is useful when you want to include local rules not included in a baseline.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the RuleIncludeLocal parameter\n$option = New-PSRuleOption -RuleIncludeLocal $True;\n</code></pre> <pre><code># PowerShell: Using the Rule.IncludeLocal hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.IncludeLocal' = $True };\n</code></pre> <pre><code># PowerShell: Using the RuleIncludeLocal parameter to set YAML\nSet-PSRuleOption -RuleIncludeLocal $True;\n</code></pre> <pre><code># YAML: Using the rule/includeLocal property\nrule:\n  includeLocal: true\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_RULE_INCLUDELOCAL=true\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_RULE_INCLUDELOCAL: true\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDELOCAL\n  value: true\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleexclude","title":"Rule.Exclude","text":"<p>The name of specific rules to exclude from being evaluated. This will exclude rules specified by <code>Rule.Include</code> or discovered from a search path.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Rule.Exclude hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Exclude' = 'Rule3','Rule4' };\n</code></pre> <pre><code># YAML: Using the rule/exclude property\nrule:\n  exclude:\n  - Rule3\n  - Rule4\n</code></pre> <pre><code># Bash: Using environment variable\nexport PSRULE_RULE_EXCLUDE='Rule3;Rule4'\n</code></pre> <pre><code># GitHub Actions: Using environment variable\nenv:\n  PSRULE_RULE_EXCLUDE: 'Rule3;Rule4'\n</code></pre> <pre><code># Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_EXCLUDE\n  value: 'Rule3;Rule4'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruletag","title":"Rule.Tag","text":"<p>A set of required key value pairs (tags) that rules must have applied to them to be included.</p> <p>Multiple values can be specified for the same tag. When multiple values are used, only one must match.</p> <p>This option can be overridden at runtime by using the <code>-Tag</code> cmdlet parameter.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the Rule.Tag hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Tag' = @{ severity = 'Critical','Warning' } };\n</code></pre> <pre><code># YAML: Using the rule/tag property\nrule:\n  tag:\n    severity: Critical\n</code></pre> <pre><code># YAML: Using the rule/tag property, with multiple values\nrule:\n  tag:\n    severity:\n    - Critical\n    - Warning\n</code></pre> <p>In the example above, rules must have a tag of <code>severity</code> set to either <code>Critical</code> or <code>Warning</code> to be included.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#suppression","title":"Suppression","text":"<p>In certain circumstances it may be necessary to exclude or suppress rules from processing objects that are in a known failed state.</p> <p>PSRule allows objects to be suppressed for a rule by TargetName. Objects that are suppressed are not processed by the rule at all but will continue to be processed by other rules.</p> <p>Rule suppression complements pre-filtering and pre-conditions.</p> <p>This option can be specified using:</p> <pre><code># PowerShell: Using the SuppressTargetName option with a hashtable\n$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\n</code></pre> <pre><code># YAML: Using the suppression property\nsuppression:\n  storageAccounts.UseHttps:\n    targetName:\n    - TestObject1\n    - TestObject3\n</code></pre> <p>In both of the above examples, <code>TestObject1</code> and <code>TestObject3</code> have been suppressed from being processed by a rule named <code>storageAccounts.UseHttps</code>.</p> <p>When to use rule suppression:</p> <ul> <li>A temporary exclusion for an object that is in a known failed state.</li> </ul> <p>When not to use rule suppression:</p> <ul> <li>An object should never be processed by any rule. Pre-filter the pipeline instead.</li> <li>The rule is not applicable because the object is the wrong type. Use pre-conditions on the rule instead.</li> </ul> <p>An example of pre-filtering:</p> <pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge'; Type = 'Equipment'; Category = 'White goods'; };\n$items += [PSCustomObject]@{ Name = 'Apple'; Type = 'Food'; Category = 'Produce'; };\n$items += [PSCustomObject]@{ Name = 'Carrot'; Type = 'Food'; Category = 'Produce'; };\n\n# Example of pre-filtering, only food items are sent to Invoke-PSRule\n$items | Where-Object { $_.Type -eq 'Food' } | Invoke-PSRule;\n</code></pre> <p>An example of pre-conditions:</p> <pre><code># A rule with a pre-condition to only process produce\nRule 'isFruit' -If { $TargetObject.Category -eq 'Produce' } {\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#example-ps-ruleyaml","title":"Example ps-rule.yaml","text":"<pre><code>#\n# PSRule example configuration\n#\n\n# Configures the repository\nrepository:\n  url: https://github.com/microsoft/PSRule\n  baseRef: main\n\n# Configure required module versions\nrequires:\n  PSRule.Rules.Azure: '&gt;=1.1.0'\n\n# Configure convention options\nconvention:\n  include:\n  - 'Convention1'\n\n# Configure execution options\nexecution:\n  hashAlgorithm: SHA256\n  duplicateResourceId: Warn\n  languageMode: ConstrainedLanguage\n  suppressionGroupExpired: Error\n  restrictScriptSource: ModuleOnly\n\n# Configure include options\ninclude:\n  module:\n  - 'PSRule.Rules.Azure'\n  path: [ ]\n\n# Configures input options\ninput:\n  format: Yaml\n  ignoreGitPath: false\n  ignoreObjectSource: true\n  ignoreRepositoryCommon: false\n  ignoreUnchangedPath: true\n  objectPath: items\n  pathIgnore:\n  - '*.Designer.cs'\n  targetType:\n  - Microsoft.Compute/virtualMachines\n  - Microsoft.Network/virtualNetworks\n\n# Configures outcome logging options\nlogging:\n  limitDebug:\n  - Rule1\n  - Rule2\n  limitVerbose:\n  - Rule1\n  - Rule2\n  ruleFail: Error\n  rulePass: Information\n\noutput:\n  as: Summary\n  banner: Minimal\n  culture:\n  - en-US\n  encoding: UTF8\n  footer: RuleCount\n  format: Json\n  jobSummaryPath: reports/summary.md\n  outcome: Fail\n  sarifProblemsOnly: false\n  style: GitHubActions\n\n# Configure rule suppression\nsuppression:\n  storageAccounts.UseHttps:\n    targetName:\n    - TestObject1\n    - TestObject3\n\n# Configure baseline options\nbinding:\n  field:\n    id:\n    - ResourceId\n    - AlternativeId\n  ignoreCase: false\n  nameSeparator: '::'\n  preferTargetInfo: true\n  targetName:\n  - ResourceName\n  - AlternateName\n  targetType:\n  - ResourceType\n  - kind\n  useQualifiedName: true\n\nconfiguration:\n  appServiceMinInstanceCount: 2\n\nrule:\n  include:\n  - rule1\n  - rule2\n  includeLocal: true\n  exclude:\n  - rule3\n  - rule4\n  tag:\n    severity:\n    - Critical\n    - Warning\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#default-ps-ruleyaml","title":"Default ps-rule.yaml","text":"<pre><code>#\n# PSRule defaults\n#\n\n# Note: Only properties that differ from the default values need to be specified.\n\n# Configure required module versions\nrequires: { }\n\n# Configure convention options\nconvention:\n  include: [ ]\n\n# Configure execution options\nexecution:\n  hashAlgorithm: SHA512\n  aliasReference: Warn\n  duplicateResourceId: Error\n  invariantCulture: Warn\n  languageMode: FullLanguage\n  initialSessionState: BuiltIn\n  restrictScriptSource: Unrestricted\n  ruleInconclusive: Warn\n  ruleSuppressed: Warn\n  suppressionGroupExpired: Warn\n  unprocessedObject: Warn\n\n# Configure include options\ninclude:\n  module: [ ]\n  path:\n  - '.ps-rule/'\n\n# Configures input options\ninput:\n  format: Detect\n  ignoreGitPath: true\n  ignoreObjectSource: false\n  ignoreRepositoryCommon: true\n  ignoreUnchangedPath: false\n  objectPath: null\n  pathIgnore: [ ]\n  targetType: [ ]\n\n# Configures outcome logging options\nlogging:\n  limitDebug: [ ]\n  limitVerbose: [ ]\n  ruleFail: None\n  rulePass: None\n\noutput:\n  as: Detail\n  banner: Default\n  culture: [ ]\n  encoding: Default\n  footer: Default\n  format: None\n  jobSummaryPath: null\n  outcome: Processed\n  sarifProblemsOnly: true\n  style: Detect\n\n# Configure rule suppression\nsuppression: { }\n\n# Configure baseline options\nbinding:\n  field: { }\n  ignoreCase: true\n  nameSeparator: '/'\n  preferTargetInfo: false\n  targetName:\n  - TargetName\n  - Name\n  targetType:\n  - PSObject.TypeNames[0]\n  useQualifiedName: false\n\nconfiguration: { }\n\nrule:\n  include: [ ]\n  includeLocal: false\n  exclude: [ ]\n  tag: { }\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> <li>New-PSRuleOption</li> <li>Set-PSRuleOption</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/","title":"Rules","text":"<p>Describes PSRule rules including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input either from a file or PowerShell pipeline. The PowerShell pipeline only available when running PSRule directly. PSRule can also be run from a continuous integration (CI) pipeline or Visual Studio Code. When using these methods, the PowerShell pipeline is not available.</p> <p>To evaluate an object PSRule can use rules defined in script or YAML.</p> <p>When using script rules:</p> <ul> <li>Each rule is defined PowerShell within a <code>.Rule.ps1</code> file by using a <code>Rule</code> block.</li> <li>PowerShell variables, functions, and cmdlets can be used just like regular PowerShell scripts.</li> <li>Built-in assertion helpers can be used to quickly build out rules.</li> <li>Pre-conditions can be defined with using a script block, type binding, or YAML-based selector.</li> </ul> <p>To learn more about assertion helpers see about_PSRule_Assert.</p> <p>When using YAML rules:</p> <ul> <li>Each rule is defined in a <code>.Rule.yaml</code> file by using the <code>Rule</code> resource.</li> <li>YAML-based expressions can be used.</li> <li>Pre-conditions can be defined with using a type binding, or YAML-based selector.</li> </ul> <p>To learn more about YAML-based expressions see about_PSRule_Expressions.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#using-pre-conditions","title":"Using pre-conditions","text":"<p>Pre-conditions are used to determine if a rule should be executed. While pre-conditions are not required for each rule, it is a good practice to define them. If a rule does not specify a pre-condition it may be executed against an object it does not expect.</p> <p>Pre-conditions come in three forms:</p> <ul> <li>Script - A PowerShell script block that is executed and if true will cause the rule to be executed.   Script block pre-conditions only work with script rules.   To use a script block pre-condition, specify the <code>-If</code> script parameter on the <code>Rule</code> block.</li> <li>Type - A type string that is compared against the bound object type.   When the type matches the rule will be executed.   To use a type pre-conditions, specify the <code>-Type</code> script parameter or <code>type</code> YAML/JSON property.</li> <li>Selector - A YAML/JSON based expression that is evaluated against the object.   When the expression matches the rule will be executed.   To use a selector pre-conditions, specify the <code>-With</code> script parameter or <code>with</code> YAML/JSON property.</li> </ul> <p>Different forms of pre-conditions can be combined. When combining pre-conditions, different forms must be all true (logical AND). i.e. Script AND Type AND Selector must be all be true for the rule to be executed.</p> <p>Multiple Type and Selector pre-conditions can be specified. If multiple Type and Selector pre-conditions are specified, only one must be true (logical OR).</p> <p>For example:</p> <pre><code># Synopsis: An example script rule with pre-conditions.\nRule 'ScriptRule' -If { $True } -Type 'CustomType1', 'CustomType2' -With 'Selector.1', 'Selector.2' {\n    # Rule condition\n}\n</code></pre> <pre><code>---\n# Synopsis: An example YAML rule with pre-conditions.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'YamlRule'\nspec:\n  type:\n  - 'CustomType1'\n  - 'CustomType2'\n  with:\n  - 'Selector.1'\n  - 'Selector.2'\n  condition: { }\n</code></pre> <pre><code>[\n  {\n    // Synopsis: An example YAML rule with pre-conditions.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Rule\",\n    \"metadata\": {\n      \"name\": \"YamlRule\"\n    },\n    \"spec\": {\n      \"type\": [\n        \"CustomType1\",\n        \"CustomType2\"\n      ],\n      \"with\": [\n        \"Selector.1\",\n        \"Selector.2\"\n      ],\n      \"condition\": {}\n    }\n  }\n]\n</code></pre> <p>Pre-conditions are evaluated in the following order: Selector, Type, then Script.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-script-rules","title":"Defining script rules","text":"<p>To define a script rule use the <code>Rule</code> keyword followed by a name and a pair of squiggly brackets <code>{</code>. Within the <code>{ }</code> one or more conditions can be used. Script rule must be defined within <code>.Rule.ps1</code> files. Multiple rules can be defined in a single file by creating multiple <code>Rule</code> blocks. Rule blocks can not be nested within each other.</p> <p>Within the <code>Rule</code> block, define one or more conditions to determine pass or fail of the rule.</p> <p>Syntax:</p> <pre><code>Rule [-Name] &lt;string&gt; [-Tag &lt;hashtable&gt;] [-When &lt;string[]&gt;] [-Type &lt;string[]&gt;] [-If &lt;scriptBlock&gt;] [-DependsOn &lt;string[]&gt;] [-Configure &lt;hashtable&gt;] [-ErrorAction &lt;ActionPreference&gt;] [-Body] {\n    ...\n}\n</code></pre> <p>Example:</p> <pre><code># Synopsis: Use a Standard load-balancer with AKS clusters.\nRule 'Azure.AKS.StandardLB' -Type 'Microsoft.ContainerService/managedClusters' -Tag @{ release = 'GA'; ruleSet = '2020_06' } {\n    $Assert.HasFieldValue($TargetObject, 'Properties.networkProfile.loadBalancerSku', 'standard');\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-yaml-rules","title":"Defining YAML rules","text":"<p>To define a YAML rule use the <code>Rule</code> resource in a YAML file. Each rule must be defined within a <code>.Rule.yaml</code> file following a standard schema. Multiple rules can be defined in a single YAML file by separating each rule with a <code>---</code>.</p> <p>Within the <code>Rule</code> resource, the <code>condition</code> property specifies conditions to pass or fail the rule.</p> <p>Syntax:</p> <pre><code>---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: '{{ Name }}'\n  tags: { }\nspec:\n  type: [ ]\n  with: [ ]\n  condition: { }\n</code></pre> <p>Example:</p> <pre><code>---\n# Synopsis: Use a Standard load-balancer with AKS clusters.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: 'Azure.AKS.StandardLB'\n  tags:\n    release: 'GA'\n    ruleSet: '2020_06'\nspec:\n  type:\n  - Microsoft.ContainerService/managedClusters\n  condition:\n    field: 'Properties.networkProfile.loadBalancerSku'\n    equals: 'standard'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-json-rules","title":"Defining JSON rules","text":"<p>To define a JSON rule use the <code>Rule</code> resource in a JSON file. Each rule must be defined within a <code>.Rule.jsonc</code> file following a standard schema. One or more rules can be defined in a single JSON array separating each rule in a JSON object.</p> <p>Within the <code>Rule</code> resource, the <code>condition</code> property specifies conditions to pass or fail the rule.</p> <p>Rules can also be defined within <code>.json</code> files. We recommend using <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>Syntax:</p> <pre><code>[\n  {\n    // Synopsis: {{ Synopsis }}\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Rule\",\n    \"metadata\": {\n      \"name\": \"{{ Name }}\",\n      \"tags\": {}\n    },\n    \"spec\": {\n      \"type\": [],\n      \"with\": [],\n      \"condition\": {}\n    }\n  }\n]\n</code></pre> <p>Example:</p> <pre><code>[\n  {\n    // Synopsis: Use a Standard load-balancer with AKS clusters.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Rule\",\n    \"metadata\": {\n      \"name\": \"Azure.AKS.StandardLB\",\n      \"tags\": {\n        \"release\": \"GA\",\n        \"ruleSet\": \"2020_06\"\n      }\n    },\n    \"spec\": {\n      \"type\": [\n        \"Microsoft.ContainerService/managedClusters\"\n      ],\n      \"condition\": {\n        \"field\": \"Properties.networkProfile.loadBalancerSku\",\n        \"equals\": \"standard\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/","title":"Selectors","text":"<p>Describes PSRule Selectors including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When evaluating an object from input, PSRule can use selectors to perform complex matches of an object.</p> <ul> <li>A selector is a YAML/JSON based expression that evaluates an object.</li> <li>Each selector is comprised of nested conditions, operators, and comparison properties.</li> <li>Selectors must use one or more available conditions with a comparison property to evaluate the object.</li> <li>Optionally a condition can be nested in an operator.</li> <li>Operators can be nested within other operators.</li> </ul> <p>The following conditions are available:</p> <ul> <li>Contains</li> <li>Count</li> <li>Equals</li> <li>EndsWith</li> <li>Exists</li> <li>Greater</li> <li>GreaterOrEquals</li> <li>HasDefault</li> <li>HasSchema</li> <li>HasValue</li> <li>In</li> <li>IsLower</li> <li>IsString</li> <li>IsArray</li> <li>IsBoolean</li> <li>IsDateTime</li> <li>IsInteger</li> <li>IsNumeric</li> <li>IsUpper</li> <li>Less</li> <li>LessOrEquals</li> <li>Match</li> <li>NotEquals</li> <li>NotIn</li> <li>NotMatch</li> <li>SetOf</li> <li>StartsWith</li> <li>Subset</li> <li>Version</li> </ul> <p>The following operators are available:</p> <ul> <li>AllOf</li> <li>AnyOf</li> <li>Not</li> </ul> <p>The following comparison properties are available:</p> <ul> <li>Field</li> <li>Name</li> <li>Type</li> </ul> <p>To learn more about conditions, operators, and properties see about_PSRule_Expressions.</p> <p>Currently the following limitations apply:</p> <ul> <li>Selectors can evaluate:<ul> <li>Fields of the target object.</li> <li>Type and name binding of the target object by using <code>name</code> and <code>type</code> comparison properties.</li> </ul> </li> <li>State variables such has <code>$PSRule</code> can not be evaluated.</li> <li>Bound fields can not be evaluated.</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#using-selectors-as-pre-conditions","title":"Using selectors as pre-conditions","text":"<p>Selectors can be referenced by name as a rule pre-condition by using the <code>-With</code> parameter. For example:</p> <pre><code>Rule 'RuleWithSelector' -With 'BasicSelector' {\n    # Rule condition\n}\n</code></pre> <p>Selector pre-conditions can be used together with type and script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before type or script block pre-conditions.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#defining-selectors","title":"Defining selectors","text":"<p>Selectors can be defined with either YAML or JSON format, and can be included with a module or standalone <code>.Rule.yaml</code> or <code>.Rule.jsonc</code> file. In either case, define a selector within a file ending with the <code>.Rule.yaml</code> or <code>.Rule.jsonc</code> extension. A selector can be defined side-by-side with other resources such as baselines or module configurations.</p> <p>Selectors can also be defined within <code>.json</code> files. We recommend using <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>Use the following template to define a selector:</p> <pre><code>---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: '{{ Name }}'\nspec:\n  if: { }\n</code></pre> <pre><code>[\n  {\n    // Synopsis: {{ Synopsis }}\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"{{ Name }}\"\n    },\n    \"spec\": {\n      \"if\": {}\n    }\n  }\n]\n</code></pre> <p>Within the <code>if</code> object, one or more conditions or logical operators can be used.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsruleyaml","title":"Example Selectors.Rule.yaml","text":"<pre><code># Example Selectors.Rule.yaml\n---\n# Synopsis: Require the CustomValue field.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: RequireCustomValue\nspec:\n  if:\n    field: 'CustomValue'\n    exists: true\n\n---\n# Synopsis: Require a Name or AlternativeName.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: RequireName\nspec:\n  if:\n    anyOf:\n    - field: 'AlternateName'\n      exists: true\n    - field: 'Name'\n      exists: true\n\n---\n# Synopsis: Require a specific CustomValue\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: RequireSpecificCustomValue\nspec:\n  if:\n    field: 'CustomValue'\n    in:\n    - 'Value1'\n    - 'Value2'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsrulejsonc","title":"Example Selectors.Rule.jsonc","text":"<pre><code>// Example Selectors.Rule.jsonc\n[\n  {\n    // Synopsis: Require the CustomValue field.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"RequireCustomValue\"\n    },\n    \"spec\": {\n      \"if\": {\n        \"field\": \"CustomValue\",\n        \"exists\": true\n      }\n    }\n  },\n  {\n    // Synopsis: Require a Name or AlternativeName.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"RequireName\"\n    },\n    \"spec\": {\n      \"if\": {\n        \"anyOf\": [\n          {\n            \"field\": \"AlternateName\",\n            \"exists\": true\n          },\n          {\n            \"field\": \"Name\",\n            \"exists\": true\n          }\n        ]\n      }\n    }\n  },\n  {\n    // Synopsis: Require a specific CustomValue\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"Selector\",\n    \"metadata\": {\n      \"name\": \"RequireSpecificCustomValue\"\n    },\n    \"spec\": {\n      \"if\": {\n        \"field\": \"CustomValue\",\n        \"in\": [\n          \"Value1\",\n          \"Value2\"\n        ]\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/","title":"Suppression Groups","text":"<p>Describes PSRule Suppression Groups including how to use and author them.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#description","title":"Description","text":"<p>PSRule executes rules to validate an object from input. When an evaluating each object, PSRule can use suppression groups to suppress rules based on a condition. Suppression groups use a Selector to determine if the rule is suppressed.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#defining-suppression-groups","title":"Defining suppression groups","text":"<p>Suppression groups can be defined using either YAML or JSON format. A suppression group can be in a standalone file or included in a module. Define suppression groups in <code>.Rule.yaml</code> or <code>.Rule.jsonc</code> files. Each suppression group may be defined individually or side-by-side with resources such as rules or baselines.</p> <p>Suppression groups can also be defined within <code>.json</code> files. We recommend using <code>.jsonc</code> to view JSON with Comments in Visual Studio Code.</p> <p>Use the following template to define a suppression group:</p> <pre><code>---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: '{{ Name }}'\nspec:\n  expiresOn: null\n  rule: []\n  if: { }\n</code></pre> <pre><code>[\n  {\n    // Synopsis: {{ Synopsis }}\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"SuppressionGroup\",\n    \"metadata\": {\n      \"name\": \"{{ Name }}\"\n    },\n    \"spec\": {\n      \"expiresOn\": null,\n      \"rule\": [],\n      \"if\": {}\n    }\n  }\n]\n</code></pre> <p>Set the <code>synopsis</code> to describe the justification for the suppression. Within the <code>rule</code> array, one or more rule names can be used. If no rules are specified, suppression will occur for all rules. Within the <code>if</code> object, one or more conditions or logical operators can be used. When the <code>if</code> condition is <code>true</code> the object will be suppressed for the current rule.</p> <p>Optionally, an expiry can be set using the <code>expiresOn</code> property. When the expiry date is reached, the suppression will no longer be applied. To configure an expiry, set a RFC3339 (ISO 8601) formatted date time using the format <code>yyyy-MM-ddTHH:mm:ssZ</code>.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#documentation","title":"Documentation","text":"<p>Suppression groups can be configured with a synopsis. When set, the synopsis will be included in output for any suppression warnings that are shown. The synopsis helps provide justification for the suppression, in a short single line message. To set the synopsis, include a comment above the suppression group <code>apiVersion</code> property.</p> <p>Alternatively, a localized synopsis can be provided in a separate markdown file. See about_PSRule_Docs for details.</p> <p>Some examples of a suppression group synopsis include:</p> <ul> <li>Ignore test objects by name.</li> <li>Ignore test objects by type.</li> <li>Ignore objects with non-production tag.</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#example-suppressiongroupsruleyaml","title":"Example SuppressionGroups.Rule.yaml","text":"<pre><code># Example SuppressionGroups.Rule.yaml\n\n---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: SuppressWithTargetName\nspec:\n  rule:\n  - 'FromFile1'\n  - 'FromFile2'\n  if:\n    name: '.'\n    in:\n    - 'TestObject1'\n    - 'TestObject2'\n\n---\n# Synopsis: Ignore test objects by type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n  name: SuppressWithTestType\nspec:\n  expiresOn: '2030-01-01T00:00:00Z'\n  rule:\n  - 'FromFile3'\n  - 'FromFile5'\n  if:\n    type: '.'\n    equals: 'TestType'\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#example-suppressiongroupsrulejsonc","title":"Example SuppressionGroups.Rule.jsonc","text":"<pre><code>// Example SuppressionGroups.Rule.jsonc\n[\n  {\n    // Synopsis: Ignore test objects by name.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"SuppressionGroup\",\n    \"metadata\": {\n      \"name\": \"SuppressWithTargetName\"\n    },\n    \"spec\": {\n      \"rule\": [\n        \"FromFile1\",\n        \"FromFile2\"\n      ],\n      \"if\": {\n        \"name\": \".\",\n        \"in\": [\n          \"TestObject1\",\n          \"TestObject2\"\n        ]\n      }\n    }\n  },\n  {\n    // Synopsis: Ignore test objects by type.\n    \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n    \"kind\": \"SuppressionGroup\",\n    \"metadata\": {\n      \"name\": \"SuppressWithTestType\"\n    },\n    \"spec\": {\n      \"expiresOn\": \"2030-01-01T00:00:00Z\",\n      \"rule\": [\n        \"FromFile3\",\n        \"FromFile5\"\n      ],\n      \"if\": {\n        \"type\": \".\",\n        \"equals\": \"TestType\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/","title":"Variables","text":"<p>Describes the automatic variables that can be used within PSRule rule definitions.</p>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#description","title":"Description","text":"<p>PSRule lets you define rules using PowerShell blocks. A rule is defined within script files by using the <code>rule</code> keyword.</p> <p>Within a rule definition, PSRule exposes a number of automatic variables that can be read to assist with rule execution. Overwriting these variables or variable properties is not supported.</p> <p>These variables are only available while <code>Invoke-PSRule</code> is executing.</p> <p>The following variables are available for use:</p> <ul> <li>$Assert</li> <li>$Configuration</li> <li>$LocalizedData</li> <li>$PSRule</li> <li>$Rule</li> <li>$TargetObject</li> </ul>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#assert","title":"Assert","text":"<p>An assertion helper with methods to evaluate objects. The <code>$Assert</code> object provides a set of built-in methods and provides a consistent variable for extension.</p> <p>Each <code>$Assert</code> method returns an <code>AssertResult</code> object that contains the result of the condition.</p> <p>The following built-in assertion methods are provided:</p> <ul> <li><code>Contains</code> - The field value must contain at least one of the strings.</li> <li><code>EndsWith</code> - The field value must match at least one suffix.</li> <li><code>FileHeader</code> - The file must contain a comment header.</li> <li><code>FilePath</code> - The file path must exist.</li> <li><code>Greater</code> - The field value must be greater.</li> <li><code>GreaterOrEqual</code> - The field value must be greater or equal to.</li> <li><code>HasDefaultValue</code> - The object should not have the field or the field value is set to the default value.</li> <li><code>HasField</code> - The object must have any of the specified fields.</li> <li><code>HasFields</code> - The object must have all of the specified fields.</li> <li><code>HasFieldValue</code> - The object must have the specified field and that field is not empty.</li> <li><code>HasJsonSchema</code> - The object must reference a JSON schema with the <code>$schema</code> field.</li> <li><code>In</code> - The field value must be included in the set.</li> <li><code>IsArray</code> - The field value must be an array.</li> <li><code>IsBoolean</code> - The field value must be a boolean.</li> <li><code>IsInteger</code> - The field value must be an integer.</li> <li><code>IsLower</code> - The field value must include only lowercase characters.</li> <li><code>IsNumeric</code> - The field value must be a numeric type.</li> <li><code>IsString</code> - The field value must be a string.</li> <li><code>IsUpper</code> - The field value must include only uppercase characters.</li> <li><code>JsonSchema</code> - The object must validate successfully against a JSON schema.</li> <li><code>Less</code> - The field value must be less.</li> <li><code>LessOrEqual</code> - The field value must be less or equal to.</li> <li><code>Match</code> - The field value matches a regular expression pattern.</li> <li><code>NotIn</code> - The field value must not be included in the set.</li> <li><code>NotMatch</code> - The field value does not match a regular expression pattern.</li> <li><code>NullOrEmpty</code> - The object must not have the specified field or it must be empty.</li> <li><code>TypeOf</code> - The field value must be of the specified type.</li> <li><code>StartsWith</code> - The field value must match at least one prefix.</li> <li><code>Version</code> - The field value must be a semantic version string.</li> </ul> <p>The <code>$Assert</code> variable can only be used within a rule definition block.</p> <p>For detailed information on the assertion helper see about_PSRule_Assert.</p> <p>Syntax:</p> <pre><code>$Assert\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: Determine if $TargetObject is valid against the provided schema\nRule 'UseJsonSchema' {\n    $Assert.JsonSchema($TargetObject, 'schemas/PSRule-options.schema.json')\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#configuration","title":"Configuration","text":"<p>A dynamic object with properties names that map to configuration values set in the baseline.</p> <p>When accessing configuration:</p> <ul> <li>Configuration keys are case sensitive.</li> <li>Configuration values are read only.</li> <li>Configuration values can be accessed through helper methods.</li> </ul> <p>The following helper methods are available:</p> <ul> <li><code>GetStringValues(string configurationKey)</code> - Returns an array of strings, based on <code>configurationKey</code>.</li> </ul> <p>Syntax:</p> <pre><code>$Configuration.&lt;configurationKey&gt;\n</code></pre> <pre><code>$Configuration.GetStringValues(&lt;configurationKey&gt;)\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: This rule uses a threshold stored as $Configuration.appServiceMinInstanceCount\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n    $TargetObject.Sku.capacity -ge $Configuration.appServiceMinInstanceCount\n} -Configure @{ appServiceMinInstanceCount = 2 }\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#localizeddata","title":"LocalizedData","text":"<p>A dynamic object with properties names that map to localized data messages in a <code>.psd1</code> file.</p> <p>When using localized data, PSRule loads localized strings as a hashtable from <code>PSRule-rules.psd1</code>.</p> <p>The following logic is used to locate <code>PSRule-rules.psd1</code>:</p> <ul> <li>If the rules are loose (not part of a module), PSRule will search for <code>PSRule-rules.psd1</code> in the <code>.\\&lt;culture&gt;\\</code> subdirectory relative to where the rule script .ps1 file is located.</li> <li>When the rules are shipped as part of a module, PSRule will search for <code>PSRule-rules.psd1</code> in the <code>.\\&lt;culture&gt;\\</code> subdirectory relative to where the module manifest .psd1 file is located.</li> </ul> <p>When accessing localized data:</p> <ul> <li>Message names are case sensitive.</li> <li>Message values are read only.</li> </ul> <p>Syntax:</p> <pre><code>$LocalizedData.&lt;messageName&gt;\n</code></pre> <p>Examples:</p> <pre><code># Data for rules stored in PSRule-rules.psd1\n@{\n    WithLocalizedDataMessage = 'LocalizedMessage for en-ZZ. Format={0}.'\n}\n</code></pre> <pre><code># Synopsis: Use -f to generate a formatted localized warning\nRule 'WithLocalizedData' {\n    Write-Warning -Message ($LocalizedData.WithLocalizedDataMessage -f $TargetObject.Type)\n}\n</code></pre> <p>This rule returns a warning message similar to:</p> <pre><code>LocalizedMessage for en-ZZ. Format=TestType.\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#psrule","title":"PSRule","text":"<p>An object representing the current context during execution.</p> <p>The following properties are available for read access:</p> <ul> <li><code>Badges</code> - A helper to generate badges within PSRule.   This property can only be called within the <code>-End</code> block of a convention.</li> <li><code>Field</code> - A hashtable of custom bound fields.   See option <code>Binding.Field</code> for more information.</li> <li><code>Input</code> - Allows adding additional input paths to the pipeline.</li> <li><code>Repository</code> - Provides access to information about the current repository.</li> <li><code>Scope</code> - Any scopes assigned to the object currently being processed by the pipeline.</li> <li><code>Source</code> - A collection of sources for the object currently being processed on the pipeline.</li> <li><code>TargetObject</code> - The object currently being processed on the pipeline.</li> <li><code>TargetName</code> - The name of the object currently being processed on the pipeline.   This property will automatically default to <code>TargetName</code> or <code>Name</code> properties of the object if they exist.</li> <li><code>TargetType</code> - The type of the object currently being processed on the pipeline.   This property will automatically bind to <code>PSObject.TypeNames[0]</code> by default.</li> <li><code>Output</code> - The output of all rules.   This property can only be called within the <code>-End</code> block of a convention.</li> </ul> <p>The following properties are available for read/ write access:</p> <ul> <li><code>Data</code> - A hashtable of custom data. This property can be populated during rule or begin/ process convention execution. Custom data is not used by PSRule directly, and is intended to be used by downstream processes that need to interpret PSRule results.</li> </ul> <p>To bind fields that already exist on the target object use custom binding and <code>Binding.Field</code>. Use custom data to store data that must be calculated during rule execution.</p> <p>The following helper methods are available:</p> <ul> <li><code>GetContent(PSObject sourceObject)</code> - Returns the content of a file as one or more objects.   The parameter <code>sourceObject</code> should be a <code>InputFileInfo</code>,<code>FileInfo</code>, or <code>Uri</code> object.</li> <li><code>GetContentField(PSObject sourceObject, string field)</code> - Returns the content of a file as one or more objects.   The parameter <code>sourceObject</code> should be a <code>InputFileInfo</code>,<code>FileInfo</code>, or <code>Uri</code> object.   The parameter <code>field</code> is an field within each object to return.   If the field does not exist on the object, an object is not returned.</li> <li><code>GetContentFirstOrDefault(PSObject sourceObject)</code> - Returns the content of a file as on object.   The parameter <code>sourceObject</code> should be a <code>InputFileInfo</code>,<code>FileInfo</code>, or <code>Uri</code> object.   If more than one object is contained in the file, only the first object is returned.   When the source file contains no objects null is returned.</li> <li><code>Import(PSObject[] sourceObject)</code> - Imports one or more source objects into the pipeline.   This method can only be called within the <code>-Initialize</code> or <code>-Begin</code> block of a convention.   Use this method to expand an object into child objects that will be processed independently.   Objects imported using this method will be excluded from the <code>Input.ObjectPath</code> option if set.</li> <li><code>ImportWithType(string type, PSObject[] sourceObject)</code> - Imports one or more source objects into the pipeline.   This method can only be called within the <code>-Initialize</code> or <code>-Begin</code> block of a convention.   Use this method to expand an object into child objects that will be processed independently.   Objects imported using this method will be excluded from the <code>Input.ObjectPath</code> option if set.   When <code>Binding.PreferTargetInfo</code> is true, the type will be automatically used as the <code>TargetType</code> for the imported object.</li> <li><code>AddService(string id, object service)</code> - Add a service to the current context.   The service can be retrieved using <code>$PSRule.GetService(id)</code>.   The service object will be available to all rules and cleaned up after all rules are executed.   Services should implement the <code>IDisposable</code> interface to perform additional cleanup.   This method can only be called within the <code>-Initialize</code> block of a convention.</li> <li><code>GetService(string id)</code> - Retrieves a service previously added by a convention.</li> <li><code>GetPath(object sourceObject, string path)</code> - Evalute an object path expression and returns the resulting objects.</li> </ul> <p>The file format is detected based on the same file formats as the option <code>Input.Format</code>. i.e. Yaml, Json, Markdown, and PowerShell Data.</p> <p>Syntax:</p> <pre><code>$PSRule\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: This rule determines if the target object matches the naming convention\nRule 'NamingConvention' {\n    $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\n</code></pre> <pre><code># Synopsis: Use allowed environment tags\nRule 'CustomData' {\n    Recommend 'Environment must be set to an allowed value'\n    Within 'Tags.environment' 'production', 'test', 'development'\n\n    if ($TargetObject.Tags.environment -in 'prod') {\n        $PSRule.Data['targetEnvironment'] = 'production'\n    }\n    elseif ($TargetObject.Tags.environment -in 'dev', 'develop') {\n        $PSRule.Data['targetEnvironment'] = 'development'\n    }\n    elseif ($TargetObject.Tags.environment -in 'tst', 'testing') {\n        $PSRule.Data['targetEnvironment'] = 'test'\n    }\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#rule","title":"Rule","text":"<p>An object representing the current rule during execution.</p> <p>The following properties are available for read access:</p> <ul> <li><code>RuleName</code> - The name of the rule.</li> <li><code>RuleId</code> - A unique identifier for the rule.</li> </ul> <p>Syntax:</p> <pre><code>$Rule\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: This rule determines if the target object matches the naming convention\nRule 'resource.NamingConvention' {\n    $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#targetobject","title":"TargetObject","text":"<p>The value of the pipeline object currently being processed. <code>$TargetObject</code> is set by using the <code>-InputObject</code> parameter of <code>Invoke-PSRule</code>.</p> <p>When more than one input object is set, each object will be processed sequentially.</p> <p>Syntax:</p> <pre><code>$TargetObject\n</code></pre> <p>Examples:</p> <pre><code># Synopsis: Check that sku capacity is set to at least 2\nRule 'HasMinInstances' {\n    $TargetObject.Sku.capacity -ge 2\n}\n</code></pre>"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#links","title":"Links","text":"<ul> <li>Invoke-PSRule</li> </ul>"},{"location":"concepts/cli/","title":"PSRule CLI","text":"<p>Abstract</p> <p>PSRule provides a command-line interface (CLI) to run rules and analyze results. This article describes the commands available in the CLI.</p> <p>For details on installing the PSRule CLI, see Install PSRule.</p>"},{"location":"concepts/cli/#commands","title":"Commands","text":"<p>The following commands are available in the CLI:</p> <ul> <li>run \u2014 Run rules against an input path and output the results.</li> <li>module \u2014 Manage or restore modules tracked by the module lock file and configured options.</li> </ul>"},{"location":"concepts/cli/#-version","title":"<code>--version</code>","text":"<p>Show the version information for PSRule.</p> <p>For example:</p> <pre><code>ps-rule --version\n</code></pre>"},{"location":"concepts/cli/#global-options","title":"Global options","text":"<p>The following global options can be used with any command:</p>"},{"location":"concepts/cli/#-option","title":"<code>--option</code>","text":"<p>Specifies the path to an options file. By default, the CLI will look for a file named <code>ps-rule.yaml</code> in the current directory.</p>"},{"location":"concepts/cli/#-h-help","title":"<code>-?</code> | <code>-h</code> | <code>--help</code>","text":"<p>Display help and usage information for the PSRule CLI and commands. To display help for a specific command, use <code>--help</code> with the command name.</p> <p>For example:</p> <pre><code>ps-rule run --help\n</code></pre>"},{"location":"concepts/cli/#-verbose","title":"<code>--verbose</code>","text":"<p>Display verbose output for the selected command.</p>"},{"location":"concepts/cli/#-debug","title":"<code>--debug</code>","text":"<p>Display debug output for the selected command.</p>"},{"location":"concepts/cli/module/","title":"ps-rule module","text":"<p>Abstract</p> <p>Use the <code>module</code> command to manage or restore modules tracked by the module lock file and configured options. (<code>ps-rule.lock.json</code>). The module lock file, provides consistent module versions across multiple machines and environments. For more information, see Lock file.</p>"},{"location":"concepts/cli/module/#usage","title":"Usage","text":"PSRule CLI command-line<pre><code>ps-rule module [subcommand] [options]\n</code></pre> <p>To use the <code>module</code> command, choose one of the available subcommands:</p> <ul> <li>module init</li> <li>module list</li> <li>module add</li> <li>module remove</li> <li>module restore</li> <li>module upgrade</li> </ul>"},{"location":"concepts/cli/module/#module-init","title":"<code>module init</code>","text":"<p>Initialize a new lock file based on existing options. Using this command, the module lock file is created or updated.</p> <p>If <code>ps-rule.yaml</code> option are configured to included module (<code>Include.Modules</code>), these a automatically added to the lock file. Any required version constraints set by the <code>Requires</code> option are taken into consideration.</p> <p>Optional parameters:</p> <ul> <li><code>--force</code> - Force the creation of a new lock file, even if one already exists.</li> </ul> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module init\n</code></pre> <p>For example, force the creation of a new lock file, even if one already exists:</p> PSRule CLI command-line<pre><code>ps-rule module init --force\n</code></pre>"},{"location":"concepts/cli/module/#module-list","title":"<code>module list</code>","text":"<p>List any module and the installed versions from the lock file.</p>"},{"location":"concepts/cli/module/#module-add","title":"<code>module add</code>","text":"<p>Add one or more modules to the module lock file. If the lock file does not exist, it is created.</p> <p>By default, the latest stable version of the module is added. Any required version constraints set by the <code>Requires</code> option are taken into consideration.</p> <p>To use a specific module version, use the <code>--version</code> argument.</p> <p>Optional parameters:</p> <ul> <li><code>--version</code> - Specifies a specific version of the module to add.   By default, the latest stable version of the module is added.   Any required version constraints set by the <code>Requires</code> option are taken into consideration.</li> </ul> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module add PSRule.Rules.Azure\n</code></pre> <p>For example, a specific version of the module is added:</p> PSRule CLI command-line<pre><code>ps-rule module add PSRule.Rules.Azure --version 1.32.1\n</code></pre>"},{"location":"concepts/cli/module/#module-remove","title":"<code>module remove</code>","text":"<p>Remove one or more modules from the lock file.</p> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module remove PSRule.Rules.Azure\n</code></pre>"},{"location":"concepts/cli/module/#module-restore","title":"<code>module restore</code>","text":"<p>Restore modules from the module lock file (<code>ps-rule.lock.json</code>) and configured options.</p> <p>Optional parameters:</p> <ul> <li><code>--force</code> - Restore modules even when an existing version that meets constraints is already installed locally.</li> </ul> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module restore\n</code></pre> <p>For example, force restore of all modules:</p> PSRule CLI command-line<pre><code>ps-rule module restore --force\n</code></pre>"},{"location":"concepts/cli/module/#module-upgrade","title":"<code>module upgrade</code>","text":"<p>Upgrade to the latest versions any modules within the lock file.</p> <p>For example:</p> PSRule CLI command-line<pre><code>ps-rule module upgrade\n</code></pre>"},{"location":"concepts/cli/module/#next-steps","title":"Next steps","text":"<p>For more information on the module lock file, see Lock file.</p> <p>To find out more about the commands available with the PSRule CLI, see PSRule CLI.</p>"},{"location":"concepts/cli/run/","title":"ps-rule run","text":"<p>Abstract</p> <p>Use the <code>run</code> command to run rules against an input path and output the results.</p>"},{"location":"concepts/cli/run/#usage","title":"Usage","text":"PSRule CLI command-line<pre><code>ps-rule run [options]\n</code></pre>"},{"location":"concepts/cli/run/#options","title":"Options","text":""},{"location":"concepts/cli/run/#-input-path-f","title":"<code>--input-path</code> | <code>-f</code>","text":"<p>The file or directory path to search for input file to use during a run. By default, this is the current working path.</p>"},{"location":"concepts/cli/run/#-module-m","title":"<code>--module</code> | <code>-m</code>","text":"<p>The name of one or more modules that contain rules or resources to use during a run.</p>"},{"location":"concepts/cli/run/#-baseline","title":"<code>--baseline</code>","text":"<p>The name of a specific baseline to use. Currently, only a single baseline can be used during a run.</p>"},{"location":"concepts/cli/run/#-outcome","title":"<code>--outcome</code>","text":"<p>Specifies the rule results to show in output. By default, <code>Pass</code>/ <code>Fail</code>/ <code>Error</code> results are shown.</p> <p>Allows filtering of results by outcome. The supported values are:</p> <ul> <li><code>Pass</code> - Results for rules that passed.</li> <li><code>Fail</code> - Results for rules that did not pass.</li> <li><code>Error</code> - Results for rules that raised an error are returned.</li> <li><code>Processed</code> - All results that were processed.   This aggregated outcome includes <code>Pass</code>, <code>Fail</code>, or <code>Error</code> results.</li> <li><code>Problem</code> - Processed results that did not pass.   This aggregated outcome includes <code>Fail</code>, or <code>Error</code> results.</li> </ul> <p>To specify multiple values, specify the parameter multiple times. For example: <code>--outcome Pass --Outcome Fail</code>.</p>"},{"location":"concepts/cli/run/#-output-o","title":"<code>--output</code> | <code>-o</code>","text":"<p>Specifies the format to use when outputting results.</p>"},{"location":"concepts/cli/run/#-output-path","title":"<code>--output-path</code>","text":"<p>Specifies a path to write results to.</p>"},{"location":"concepts/cli/run/#next-steps","title":"Next steps","text":"<p>To find out more about the commands available with the PSRule CLI, see PSRule CLI.</p>"},{"location":"expressions/functions/","title":"Functions","text":"<p>Abstract</p> <p>Functions are an advanced language feature specific to YAML and JSON expressions. That extend the language to allow for more complex use cases with expressions. Functions don't apply to script expressions because PowerShell already has rich support for complex manipulation.</p> <p>Experimental</p> <p>Functions are a work in progress and subject to change. We hope to add more functions, broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.</p> <p>Functions cover two (2) main scenarios:</p> <ul> <li>Transformation \u2014 you need to perform minor transformation before a condition.</li> <li>Configuration \u2014 you want to configure an input into a condition.</li> </ul>"},{"location":"expressions/functions/#using-functions","title":"Using functions","text":"<p>It may be necessary to perform minor transformation before evaluating a condition.</p> <ul> <li><code>boolean</code> - Convert a value to a boolean.</li> <li><code>concat</code> - Concatenate multiple values.</li> <li><code>configuration</code> - Get a configuration value.</li> <li><code>first</code> - Return the first element in an array or the first character of a string.</li> <li><code>integer</code> - Convert a value to an integer.</li> <li><code>last</code> - Return the last element in an array or the last character of a string.</li> <li><code>padLeft</code> - Pad a value with a character on the left to meet the specified length.</li> <li><code>padRight</code> - Pad a value with a character on the right to meet the specified length.</li> <li><code>path</code> - Get a value from an object path.</li> <li><code>replace</code> - Replace an old string with a new string.</li> <li><code>split</code> - Split a string into an array by a delimiter.</li> <li><code>string</code> - Convert a value to a string.</li> <li><code>substring</code> - Extract a substring from a string.</li> <li><code>trim</code> - Remove whitespace from the start and end of a string.</li> </ul>"},{"location":"expressions/functions/#supported-conditions","title":"Supported conditions","text":"<p>Currently functions are only supported on a subset of conditions. The conditions that are supported are:</p> <ul> <li><code>equals</code></li> <li><code>notEquals</code></li> <li><code>count</code></li> <li><code>less</code></li> <li><code>lessOrEquals</code></li> <li><code>greater</code></li> <li><code>greaterOrEquals</code></li> </ul>"},{"location":"expressions/functions/#examples","title":"Examples","text":"YAML<pre><code>---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example1\nspec:\n  if:\n    value:\n      $:\n        substring:\n          path: name\n        length: 7\n    equals: TestObj\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example2\nspec:\n  if:\n    value:\n      $:\n        configuration: 'ConfigArray'\n    count: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example3\nspec:\n  if:\n    value:\n      $:\n        boolean: true\n    equals: true\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example4\nspec:\n  if:\n    value:\n      $:\n        concat:\n        - path: name\n        - string: '-'\n        - path: name\n    equals: TestObject1-TestObject1\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example5\nspec:\n  if:\n    value:\n      $:\n        integer: 6\n    greater: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example6\nspec:\n  if:\n    value: TestObject1-TestObject1\n    equals:\n      $:\n        concat:\n        - path: name\n        - string: '-'\n        - path: name\n</code></pre>"},{"location":"expressions/functions/#recommended-content","title":"Recommended content","text":"<ul> <li>Create a standalone rule</li> <li>Expressions</li> <li>Sub-selectors</li> </ul>"},{"location":"expressions/sub-selectors/","title":"Sub-selectors","text":"<p>Abstract</p> <p>This topic covers sub-selectors which are a PSRule language feature specific to YAML and JSON expressions. They are useful for filtering out objects that you do not want to evaluate. Sub-selectors don't apply to script expressions because PowerShell already has rich support for filtering.</p> <p>Experimental</p> <p>Sub-selectors are a work in progress and subject to change. We hope to add broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.</p> <p>Sub-selectors cover two (2) main scenarios:</p> <ul> <li>Pre-conditions \u2014 you want to filtering out objects before a rule is run.</li> <li>Object filtering \u2014 you want to limit a condition to specific elements in a list of items.</li> </ul>"},{"location":"expressions/sub-selectors/#pre-conditions","title":"Pre-conditions","text":"<p>PSRule can process many different types of objects. Rules however, are normally written to test a specific property or type of object. So it is important that rules only run on objects that you want to evaluate. Pre-condition sub-selectors are one way you can determine if a rule should be run.</p> <p>To use a sub-selector as a pre-condition, use the <code>where</code> property, directly under the <code>spec</code>. The expressions in the sub-selector follow the same form that you can use in rules.</p> <p>For example:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector precondition.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.Precondition\nspec:\n  where:\n    field: 'kind'\n    equals: 'api'\n  condition:\n    field: resources\n    count: 10\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector precondition.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.Precondition\"\n  },\n  \"spec\": {\n    \"where\": {\n      \"field\": \"kind\",\n      \"equals\": \"api\"\n    },\n    \"condition\": {\n      \"field\": \"resources\",\n      \"count\": 10\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ol> <li>The <code>where</code> property is the start of a sub-selector.</li> <li>The sub-selector checks if the <code>kind</code> property equals <code>api</code>.</li> </ol> <p>The rule does not run if the:</p> <ul> <li>The object does not have a <code>kind</code> property. OR</li> <li>The value of the <code>kind</code> property is not <code>api</code>.</li> </ul> <p>Tip</p> <p>Other types of pre-conditions also exist that allow you to filter based on type or by a shared selector.</p>"},{"location":"expressions/sub-selectors/#object-filter","title":"Object filter","text":"<p>When you are evaluating an object, you can use sub-selectors to limit the condition. This is helpful when dealing with properties that are a list of items. Properties that contain a list of items may contain a sub-set of items that you want to evaluate.</p> <p>For example, the object may look like this:</p> YAMLJSON <pre><code>name: app1\ntype: Microsoft.Web/sites\nresources:\n- name: web\n  type: Microsoft.Web/sites/config\n  properties:\n    detailedErrorLoggingEnabled: true\n</code></pre> <pre><code>{\n  \"name\": \"app1\",\n  \"type\": \"Microsoft.Web/sites\",\n  \"resources\": [\n    {\n      \"name\": \"web\",\n      \"type\": \"Microsoft.Web/sites/config\",\n      \"properties\": {\n        \"detailedErrorLoggingEnabled\": true\n      }\n    }\n  ]\n}\n</code></pre> <p>A rule to test if any sub-resources with the <code>detailedErrorLoggingEnabled</code> set to <code>true</code> exist might look like this:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.Filter\nspec:\n  condition:\n    field: resources\n    where:\n      type: '.'\n      equals: 'Microsoft.Web/sites/config'\n    allOf:\n    - field: properties.detailedErrorLoggingEnabled\n      equals: true\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector filter.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.Filter\"\n  },\n  \"spec\": {\n    \"condition\": {\n      \"field\": \"resources\",\n      \"where\": {\n        \"type\": \".\",\n        \"equals\": \"Microsoft.Web/sites/config\"\n      },\n      \"allOf\": [\n        {\n          \"field\": \"properties.detailedErrorLoggingEnabled\",\n          \"equals\": true\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ul> <li>If the array property <code>resources</code> exists, any items with a type of <code>Microsoft.Web/sites/config</code> are evaluated.<ul> <li>Each item must have the <code>properties.detailedErrorLoggingEnabled</code> property set to <code>true</code> to pass.</li> <li>Items without the <code>properties.detailedErrorLoggingEnabled</code> property fail.</li> <li>Items with the <code>properties.detailedErrorLoggingEnabled</code> property set to a value other then <code>true</code> fail.</li> </ul> </li> <li>If the <code>resources</code> property does not exist, the rule fails.</li> <li>If the <code>resources</code> property exists but has 0 items of type <code>Microsoft.Web/sites/config</code>, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> but any fail, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> and all pass, the rule passes.</li> </ul>"},{"location":"expressions/sub-selectors/#when-there-are-no-results","title":"When there are no results","text":"<p>Given the example, is important to understand what happens by default if:</p> <ul> <li>The <code>resources</code> property doesn't exist. OR</li> <li>The <code>resources</code> property doesn't contain any items that match the sub-selector condition.</li> </ul> <p>In either of these two cases, the sub-selector will return <code>false</code> and fail the rule. The rule fails because there is no secondary conditions that could be used instead.</p> <p>If this was not the desired behavior, you could:</p> <ul> <li>Use a pre-condition to avoid running the rule.</li> <li>Group the sub-selector into a <code>anyOf</code>, and provide a secondary condition.</li> <li>Use a quantifier to determine how many items must match sub-selector and match the <code>allOf</code> / <code>anyOf</code> operator.</li> </ul> <p>For example:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.FilterOr\nspec:\n  condition:\n    anyOf:\n\n    - field: resources\n      where:\n        type: '.'\n        equals: 'Microsoft.Web/sites/config'\n      allOf:\n      - field: properties.detailedErrorLoggingEnabled\n        equals: true\n\n    - field: resources\n      exists: false\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector filter.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.FilterOr\"\n  },\n  \"spec\": {\n    \"condition\": {\n      \"anyOf\": [\n        {\n          \"field\": \"resources\",\n          \"where\": {\n            \"type\": \".\",\n            \"equals\": \"Microsoft.Web/sites/config\"\n          },\n          \"allOf\": [\n            {\n              \"field\": \"properties.detailedErrorLoggingEnabled\",\n              \"equals\": true\n            }\n          ]\n        },\n        {\n          \"field\": \"resources\",\n          \"exists\": false\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ul> <li>If the array property <code>resources</code> exists, any items with a type of <code>Microsoft.Web/sites/config</code> are evaluated.<ul> <li>Each item must have the <code>properties.detailedErrorLoggingEnabled</code> property set to <code>true</code> to pass.</li> <li>Items without the <code>properties.detailedErrorLoggingEnabled</code> property fail.</li> <li>Items with the <code>properties.detailedErrorLoggingEnabled</code> property set to a value other then <code>true</code> fail.</li> </ul> </li> <li>If the <code>resources</code> property does not exist, the rule passes.</li> <li>If the <code>resources</code> property exists but has 0 items of type <code>Microsoft.Web/sites/config</code>, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> but any fail, the rule fails.</li> <li>If the <code>resources</code> property exists and has any items of type <code>Microsoft.Web/sites/config</code> and all pass, the rule passes.</li> </ul>"},{"location":"expressions/sub-selectors/#using-a-quantifier-with-sub-selectors","title":"Using a quantifier with sub-selectors","text":"<p>When iterating over a list of items, you may want to determine how many items must match. A quantifier determines how many items in the list match. Matching items must be:</p> <ul> <li>Selected by the sub-selector.</li> <li>Match the condition of the operator.</li> </ul> <p>Supported quantifiers are:</p> <ul> <li><code>count</code> \u2014 The number of items must equal then the specified value.</li> <li><code>less</code> \u2014 The number of items must less then the specified value.</li> <li><code>lessOrEqual</code> \u2014 The number of items must less or equal to the specified value.</li> <li><code>greater</code> \u2014 The number of items must greater then the specified value.</li> <li><code>greaterOrEqual</code> \u2014 The number of items must greater or equal to the specified value.</li> </ul> <p>For example:</p> YAMLJSON <pre><code>---\n# Synopsis: A rule with a sub-selector quantifier.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.Subselector.Quantifier\nspec:\n  condition:\n    field: resources\n    where:\n      type: '.'\n      equals: 'Microsoft.Web/sites/config'\n    greaterOrEqual: 1\n    allOf:\n    - field: properties.detailedErrorLoggingEnabled\n      equals: true\n</code></pre> <pre><code>{\n  // Synopsis: A rule with a sub-selector quantifier.\n  \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n  \"kind\": \"Rule\",\n  \"metadata\": {\n    \"name\": \"Json.Subselector.Quantifier\"\n  },\n  \"spec\": {\n    \"condition\": {\n      \"field\": \"resources\",\n      \"where\": {\n        \"type\": \".\",\n        \"equals\": \"Microsoft.Web/sites/config\"\n      },\n      \"greaterOrEqual\": 1,\n      \"allOf\": [\n        {\n          \"field\": \"properties.detailedErrorLoggingEnabled\",\n          \"equals\": true\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>In the example:</p> <ul> <li>If the array property <code>resources</code> exists, any items with a type of <code>Microsoft.Web/sites/config</code> are evaluated.<ul> <li>Each item must have the <code>properties.detailedErrorLoggingEnabled</code> property set to <code>true</code> to pass.</li> <li>The number of items that pass must be greater or equal to <code>1</code>.</li> </ul> </li> <li>If the <code>resources</code> property does not exist or is empty, the number of items is <code>0</code> which fails greater or equal to <code>1</code>.</li> </ul>"},{"location":"expressions/sub-selectors/#recommended-content","title":"Recommended content","text":"<ul> <li>Create a standalone rule</li> <li>Functions</li> <li>Expressions</li> </ul>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/","title":"Keywords","text":"<p>Describes the language keywords that can be used within PSRule rule definitions.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#description","title":"Description","text":"<p>PSRule lets you define rules using PowerShell blocks. To define a rule use the <code>Rule</code> keyword.</p> <ul> <li>Rule - Creates a rule definition.</li> </ul> <p>The following are the built-in keywords that can be used within a rule definition:</p> <ul> <li>AnyOf - Assert that any of the child expressions must be true.</li> <li>AllOf - Assert that all of the child expressions must be true.</li> <li>Exists - Assert that a field or property must exist.</li> <li>Match - Assert that the field must match any of the regular expressions.</li> <li>Reason - Return a reason for why the rule failed.</li> <li>Recommend - Return a recommendation to resolve the issue and pass the rule.</li> <li>TypeOf - Assert that the object must be of a specific type.</li> <li>Within - Assert that the field must match any of the values.</li> </ul> <p>A subset of built-in keywords can be used within script preconditions:</p> <ul> <li>Exists - Assert that a field or property must exist.</li> <li>Match - Assert that the field must match any of the regular expressions.</li> <li>TypeOf - Assert that the object must be of a specific type.</li> <li>Within - Assert that the field must match any of the values.</li> </ul>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#rule","title":"Rule","text":"<p>A <code>Rule</code> definition describes an individual business rule that will be executed against each input object. Input objects can be passed on the PowerShell pipeline or supplied from file.</p> <p>To define a Rule use the <code>Rule</code> keyword followed by a name and a pair of squiggly brackets <code>{</code>. Within the <code>{ }</code> one or more conditions can be used.</p> <p>Conditions determine if the input object either Pass or Fail the rule.</p> <p>Syntax:</p> <pre><code>Rule [-Name] &lt;string&gt; [-Ref &lt;string&gt;] [-Alias &lt;string[]&gt;] [-Tag &lt;hashtable&gt;] [-When &lt;string[]&gt;] [-Type &lt;string[]&gt;] [-If &lt;scriptBlock&gt;] [-DependsOn &lt;string[]&gt;] [-Configure &lt;hashtable&gt;] [-ErrorAction &lt;ActionPreference&gt;] [-Body] {\n    ...\n}\n</code></pre> <ul> <li><code>Name</code> - The name of the rule definition. Each rule name must be unique. When packaging rules within a module, rule names must only be unique within the module.</li> <li><code>Ref</code> - An optional stable and opaque identifier that can be used to reference the rule.</li> <li><code>Alias</code> - A list of alternative names that can be used to reference the rule.</li> <li><code>Tag</code> - A hashtable of key/ value metadata that can be used to filter and identify rules and rule results.</li> <li><code>When</code> - A selector precondition that must evaluate true before the rule is executed.</li> <li><code>Type</code> - A type precondition that must match the TargetType of the pipeline object before the rule is executed.</li> <li><code>If</code> - A script precondition that must evaluate to <code>$True</code> before the rule is executed.</li> <li><code>DependsOn</code> - A list of rules this rule depends on. Rule dependencies must execute successfully before this rule is executed.</li> <li><code>Configure</code> - A set of default configuration values. These values are only used when the baseline configuration does not contain the key.</li> <li><code>ErrorAction</code> - The action to take when an error occur. Only a subset of preferences are supported, either <code>Stop</code> or <code>Ignore</code>. When <code>-ErrorAction</code> is not specified the default preference is <code>Stop</code>. When errors are ignored a rule will pass or fail based on the rule condition. Uncaught exceptions will still cause rule return an error outcome.</li> <li><code>Body</code> - A script block that specifies one or more conditions that are required for the rule to Pass.</li> </ul> <p>A condition is any valid PowerShell that return either <code>$True</code> or <code>$False</code>. Optionally, PSRule keywords can be used to help build out conditions quickly. When a rule contains more then one condition, all must return <code>$True</code> for the rule to Pass. If any one condition returns <code>$False</code> the rule has failed.</p> <p>The following restrictions apply:</p> <ul> <li>Rule conditions should only return <code>$True</code> or <code>$False</code>. Other objects should be caught with <code>Out-Null</code> or null assigned like <code>$Null = SomeCommand</code>.</li> <li>The <code>Rule</code> keyword can not be nested in a <code>Rule</code> definition.</li> <li>Variables and functions defined within <code>.Rule.ps1</code> files, but outside the <code>Rule</code> definition block are not accessible unless the <code>Global</code> scope is applied.</li> <li>Functions and variables within the caller's scope (the scope calling <code>Invoke-PSRule</code>, <code>Get-PSRule</code>, <code>Test-PSRuleTarget</code>) are not accessible.</li> <li>Cmdlets that require user interaction are not supported, i.e. <code>Read-Host</code>.</li> <li>Script preconditions can contain <code>Exists</code>, <code>Match</code>, <code>TypeOf</code> and <code>Within</code> keywords.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: This rule checks for the presence of a name field\nRule 'NameMustExist' {\n    Exists 'Name'\n}\n</code></pre> <pre><code># Synopsis: This rule checks that the title field is valid, when the rule NameMustExist is successful\nRule 'TitleIsValid' -DependsOn 'NameMustExist' {\n    Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n</code></pre> <pre><code># Synopsis: This rule uses a threshold stored as $Configuration.minInstanceCount\nRule 'HasMinInstances' {\n    $TargetObject.Sku.capacity -ge $Configuration.minInstanceCount\n} -Configure @{ minInstanceCount = 2 }\n</code></pre> <pre><code># Synopsis: This rule still passes because errors are ignored\nRule 'WithRuleErrorActionIgnore' -ErrorAction Ignore {\n    Write-Error 'Some error';\n    $True;\n}\n</code></pre>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#exists","title":"Exists","text":"<p>The <code>Exists</code> assertion is used within a <code>Rule</code> definition to assert that a field or property must exist on the pipeline object.</p> <p>Syntax:</p> <pre><code>Exists [-Field] &lt;string[]&gt; [-CaseSensitive] [-Not] [-All] [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>Field</code> - One or more fields/ properties that must exist on the pipeline object.</li> <li><code>CaseSensitive</code> - The field name must match exact case.</li> <li><code>Not</code> - Instead of checking if the field names exists they should not exist.</li> <li><code>All</code> - All fields must exist on the pipeline object, instead of only one.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Checks for the presence of a name property\nRule 'nameMustExist' {\n    Exists 'Name'\n}\n</code></pre> <pre><code># Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n    Exists 'metadata.name'\n}\n</code></pre> <pre><code># Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n    $TargetObject.metadata | Exists 'name'\n}\n</code></pre> <pre><code># Synopsis: Checks that the NotName property does not exist\nRule 'NotNameMustNotExist' {\n    Exists -Not 'NotName'\n}\n</code></pre> <pre><code># Synopsis: Checks one of Name or AlternativeName properties exist\nRule 'EitherMustExist' {\n    Exists 'Name', 'AlternativeName'\n}\n</code></pre> <pre><code># Synopsis: Checks that both Name and Type properties exist\nRule 'AllMustExist' {\n    Exists 'Name', 'Type' -All\n}\n</code></pre> <p>Output:</p> <p>If any the specified fields exists then <code>Exists</code> will return <code>$True</code>, otherwise <code>$False</code>.</p> <p>If <code>-Not</code> is used, then if any of the fields exist then <code>Exists</code> will return <code>$False</code> otherwise <code>$True</code>.</p> <p>If <code>-All</code> is used, then then all of the fields must exist, or not with the <code>-Not</code> switch. If all fields exist then <code>Exists</code> will return <code>$True</code>, otherwise <code>$False</code>. If <code>-Not</code> is used with <code>-All</code>, if all of the fields exist <code>Exists</code> will return <code>$False</code> otherwise <code>$True</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#match","title":"Match","text":"<p>The <code>Match</code> assertion is used within a <code>Rule</code> definition to assert that the value of a field or property from pipeline data must match one or more regular expressions. To optionally perform a case sensitive match use the <code>-CaseSensitive</code> switch, otherwise a case insensitive match will be used.</p> <p>Syntax:</p> <pre><code>Match [-Field] &lt;string&gt; [-Expression] &lt;string[]&gt; [-CaseSensitive] [-Not] [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>Field</code> - The name of the field that will be evaluated on the pipeline object.</li> <li><code>Expression</code> - One or more regular expressions that will be used to match the value of the field.</li> <li><code>CaseSensitive</code> - The field value must match exact case.</li> <li><code>Not</code> - Instead of checking the field value matches, the field value must not match any of the expressions.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Check that PhoneNumber is complete and formatted correctly\nRule 'validatePhoneNumber' {\n    Match 'PhoneNumber' '^(\\+61|0)([0-9] {0,1}){8}[0-9]$'\n}\n</code></pre> <p>Output:</p> <p>If any of the specified regular expressions match the field value then <code>Match</code> returns <code>$True</code>, otherwise <code>$False</code>.</p> <p>When <code>-Not</code> is used, if any of the regular expressions match the field value with <code>Match</code> return <code>$False</code>, otherwise <code>$True</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#within","title":"Within","text":"<p>The <code>Within</code> assertion is used within a <code>Rule</code> definition to assert that the value of a field or property from pipeline data must equal an item from a supplied list of allowed values. To optionally perform a case sensitive match use the <code>-CaseSensitive</code> switch, otherwise a case insensitive match will be used.</p> <p>Syntax:</p> <pre><code>Within [-Field] &lt;string&gt; [-Not] [-Like] [-Value] &lt;PSObject[]&gt; [-CaseSensitive] [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>Field</code> - The name of the field that will be evaluated on the pipeline object.</li> <li><code>Value</code> - A list of values that the field value must match.</li> <li><code>CaseSensitive</code> - The field value must match exact case. Only applies when the field value and allowed values are strings.</li> <li><code>Not</code> - Instead of checking the field value matches, the field value must not match any of the supplied values.</li> <li><code>Like</code> - Instead of using an exact match, a wildcard match is used. This switch can only be used when <code>Value</code> a string type.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n    Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n</code></pre> <pre><code># Synopsis: Ensure that the title field is not one of the specified values\nRule 'validateTitle' {\n    Within 'Title' -Not 'Mr', 'Sir'\n}\n</code></pre> <pre><code># Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n    Within 'Title' -Like 'Mr', 'M*s'\n}\n</code></pre> <p>Output:</p> <p>If any of the values match the field value then <code>Within</code> returns <code>$True</code>, otherwise <code>$False</code>.</p> <p>When <code>-Not</code> is used, if any of the values match the field value with <code>Within</code> return <code>$False</code>, otherwise <code>$True</code>.</p> <p>When <code>-Like</code> is used, the field value is matched against one or more wildcard expressions.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#allof","title":"AllOf","text":"<p>The <code>AllOf</code> assertion is used within a <code>Rule</code> definition to aggregate the result of assertions within a pair of squiggly brackets <code>{ }</code>. <code>AllOf</code> is functionally equivalent to a binary and, where when all of the contained assertions return <code>$True</code>, <code>AllOf</code> will return <code>$True</code>.</p> <p>Syntax:</p> <pre><code>AllOf [-Body] {\n    &lt;assertion&gt;\n    [&lt;assertion&gt;]\n    ...\n}\n</code></pre> <ul> <li><code>Body</code> - A script block definition of the containing one or more PSRule keywords and PowerShell expressions.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: The Name field must exist and have a value of either John or Jane\nRule 'nameCheck' {\n    AllOf {\n        Exists 'Name'\n        Within 'Name' 'John', 'Jane'\n    }\n}\n</code></pre> <p>Output:</p> <p>If all of the assertions return <code>$True</code> AllOf will return <code>$True</code>, otherwise <code>$False</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#anyof","title":"AnyOf","text":"<p>The <code>AnyOf</code> assertion is used within a <code>Rule</code> definition to aggregate the result of assertions within a pair of squiggly brackets <code>{ }</code>. <code>AnyOf</code> is functionally equivalent to a binary or, where if any of the contained assertions returns <code>$True</code>, <code>AnyOf</code> will return <code>$True</code>.</p> <p>Syntax:</p> <pre><code>AnyOf [-Body] {\n    &lt;assertion&gt;\n    [&lt;assertion&gt;]\n    ...\n}\n</code></pre> <ul> <li><code>Body</code> - A script block definition of the containing one or more PSRule keywords and PowerShell expressions.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: The Last or Surname field must exist\nRule 'personCheck' {\n    AnyOf {\n        Exists 'Last'\n        Exists 'Surname'\n    }\n}\n</code></pre> <p>Output:</p> <p>If any of the assertions return <code>$True</code> AnyOf will return <code>$True</code>, otherwise <code>$False</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#typeof","title":"TypeOf","text":"<p>The <code>TypeOf</code> assertion is used within a <code>Rule</code> definition to evaluate if the pipeline object matches one or more of the supplied type names.</p> <p>Syntax:</p> <pre><code>TypeOf [-TypeName] &lt;string[]&gt; [-Reason &lt;string&gt;] [-InputObject &lt;PSObject&gt;]\n</code></pre> <ul> <li><code>TypeName</code> - One or more type names which will be evaluated against the pipeline object. <code>TypeName</code> is case sensitive.</li> <li><code>Reason</code> - A custom reason provided if the condition fails.</li> <li><code>InputObject</code> - Supports objects being piped directly.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: The object must be a hashtable\nRule 'objectType' {\n    TypeOf 'System.Collections.Hashtable'\n}\n</code></pre> <p>Output:</p> <p>If any the specified type names match the pipeline object then TypeOf will return <code>$True</code>, otherwise <code>$False</code>.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#reason","title":"Reason","text":"<p>The <code>Reason</code> keyword is used within a <code>Rule</code> definition to provide a message that indicates the reason the rule failed. The reason is included in detailed results.</p> <p>A reason is only included when the rule fails or errors. The outcomes <code>Pass</code> and <code>None</code> do not include reason.</p> <p>Use this keyword when you want to implement custom logic. Built-in keywords including <code>Exists</code>, <code>Match</code>, <code>Within</code> and <code>TypeOf</code> automatically include a reason when they fail.</p> <p>Syntax:</p> <pre><code>Reason [-Text] &lt;string&gt;\n</code></pre> <ul> <li><code>Text</code> - A message that includes the reason for the failure.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Provide reason the rule failed\nRule 'objectRecommend' {\n    Reason 'A minimum of two (2) instances are required'\n    $TargetObject.count -ge 2\n}\n</code></pre> <p>Output:</p> <p>None.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#recommend","title":"Recommend","text":"<p>The <code>Recommend</code> keyword is used within a <code>Rule</code> definition to provide a recommendation to resolve the issue and pass the rule. This may include manual steps to change that state of the object or the desired state accessed by the rule.</p> <p>The recommendation can only be set once per rule. Each object will use the same recommendation.</p> <p>Syntax:</p> <pre><code>Recommend [-Text] &lt;string&gt;\n</code></pre> <ul> <li><code>Text</code> - A message that includes the process to resolve the issue and pass the rule.</li> </ul> <p>Examples:</p> <pre><code># Synopsis: Provide recommendation to resolve the issue\nRule 'objectRecommend' {\n    Recommend 'Use at least two (2) instances'\n    $TargetObject.count -ge 2\n}\n</code></pre> <p>Output:</p> <p>None.</p>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#examples","title":"Examples","text":"<pre><code># Synopsis: App Service Plan has multiple instances\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n    Recommend 'Use at least two (2) instances'\n\n    $TargetObject.Sku.capacity -ge 2\n}\n</code></pre>"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#links","title":"Links","text":"<ul> <li>[Invoke-PSRule]</li> </ul>"},{"location":"quickstart/standalone-rule/","title":"Create a standalone rule","text":"<p>You can use PSRule to create tests for PowerShell objects piped to PSRule for validation. Each test is called a rule.</p> <p>PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.</p> <p>Abstract</p> <p>This topic covers how to create a rule using YAML, JSON, and PowerShell by example. In this quickstart, will be using native PowerShell objects. For an example of reading objects from disk, continue reading Testing infrastructure.</p>"},{"location":"quickstart/standalone-rule/#prerequisites","title":"Prerequisites","text":"<p>For this quickstart, PSRule must be installed locally on MacOS, Linux, or Windows. To install PSRule locally, open PowerShell and run the following <code>Install-Module</code> command. If you don't have PowerShell installed, complete Installing PowerShell first.</p> PowerShell<pre><code>Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\n</code></pre> <p>Tip</p> <p>PowerShell is installed by default on Windows. If these instructions don't work for you, your administrator may have restricted how PowerShell can be used in your environment. You or your administrator may be able to install PSRule for all users as a local administrator. See Getting the modules for instructions on how to do this.</p> <p>Tip</p> <p>To make you editing experience even better, consider installing the Visual Studio Code extension.</p>"},{"location":"quickstart/standalone-rule/#scenario-test-for-image-files","title":"Scenario - Test for image files","text":"<p>In our quickstart scenario, we have been tasked with creating a rule to test for image files. When a file ending with the <code>.jpg</code> or <code>.png</code> extension is found the rule should fail.</p> <p>We will be using the following PowerShell code to get a list of files.</p> PowerShell<pre><code>$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\n</code></pre> <p>Info</p> <p>The path to search <code>$Env:HOME</code> defaults to the current user's home directory. This directory is used so this quickstart works on Windows and Linux operating systems. Feel free to update this path to a more suitable directory on your local machine.</p>"},{"location":"quickstart/standalone-rule/#define-the-file-type-rule","title":"Define the file type rule","text":"<p>Before an object can be tested with PSRule, one or more rules must be defined. Each rule is defined in a file named with the suffix <code>.Rule.yaml</code>, <code>.Rule.jsonc</code>, or <code>.Rule.ps1</code>. Multiple rules can be defined in a single file.</p> <p>A rule that fail on files with <code>.jpg</code> or <code>.png</code> extensions is shown in YAML, JSON, and PowerShell formats. You only need to choose one format, however you can choose to create all three to try out each format.</p> YAMLJSONPowerShell <p>Create the <code>FileType.Rule.yaml</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>FileType.Rule.yaml</code>.</p> YAML<pre><code>---\n# Synopsis: Image files are not permitted.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.FileType\nspec:\n  type:\n  - System.IO.FileInfo\n  condition:\n    field: Extension\n    notIn:\n    - .jpg\n    - .png\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Yaml.FileType</code>.</li> <li>The <code>type</code> property ensures the rule will only run for file info objects.     Other objects that might be piped to PSRule will be skipped by the <code>Yaml.FileType</code> rule.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each file returned with <code>Get-ChildItem</code>.     Specifically, the <code>Extension</code> property of each <code>FileInfo</code> object will be compared.     The value of <code>Extension</code> should not be either <code>.jpg</code> or <code>.png</code>.</li> </ol> <p>Create the <code>FileType.Rule.jsonc</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>FileType.Rule.jsonc</code>.</p> JSON<pre><code>[\n    {\n        // Synopsis: Image files are not permitted.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Json.FileType\"\n        },\n        \"spec\": {\n            \"type\": [\n                \"System.IO.FileInfo\"\n            ],\n            \"condition\": {\n                \"field\": \"Extension\",\n                \"notIn\": [\n                    \".jpg\",\n                    \".png\"\n                ]\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Json.FileType</code>.</li> <li>The <code>type</code> property ensures the rule will only run for file info objects.     Other objects that might be piped to PSRule will be skipped by the <code>Json.FileType</code> rule.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each file returned with <code>Get-ChildItem</code>.     Specifically, the <code>Extension</code> property of each <code>FileInfo</code> object will be compared.     The value of <code>Extension</code> should not be either <code>.jpg</code> or <code>.png</code>.</li> </ol> <p>Create the <code>FileType.Rule.ps1</code> file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you save <code>FileType.Rule.ps1</code>.</p> PowerShell<pre><code># Synopsis: Image files are not permitted.\nRule 'PS.FileType' -Type 'System.IO.FileInfo' {\n    $Assert.NotIn($TargetObject, 'Extension', @('.jpg', '.png'))\n}\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>PS.FileType</code>.</li> <li>The <code>-Type</code> parameter ensures the rule will only run for file info objects.     Other objects that might be piped to PSRule will be skipped by the <code>PS.FileType</code> rule.</li> <li>The condition contained within the curly braces <code>{ }</code> determines the checks PSRule will use to test each file returned with <code>Get-ChildItem</code>.</li> <li>The <code>$Assert.NotIn</code> method checks the <code>Extension</code> property is not set to <code>.jpg</code> or <code>.png</code>.</li> </ol>"},{"location":"quickstart/standalone-rule/#testing-file-extensions","title":"Testing file extensions","text":"<p>You can test the rule by using the <code>Invoke-PSRule</code> command. For example:</p> PowerShell<pre><code>$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\n\n# The path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\FileType.Rule.ps1'\n# Or the directory can be used to find all rules in the path:\n# $rulePath = 'C:\\temp\\'\n\n# Test the rule\n$files | Invoke-PSRule -Path $rulePath\n</code></pre> <p>After running <code>Invoke-PSRule</code> you will get output which includes all files in the pathToSeach. Files with a <code>.jpg</code> or <code>.png</code> extension should have the outcome of <code>Fail</code>. All other files should report an outcome of <code>Pass</code>.</p> <p>For example:</p> Output<pre><code>   TargetName: main.html\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nYaml.FileType                       Pass       Image files are not permitted.\n\n   TargetName: favicon.png\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nYaml.FileType                       Fail       Image files are not permitted.\n</code></pre> <p>Tip</p> <ul> <li>If you didn't get any results with <code>Fail</code> try creating or saving a <code>.jpg</code> file in pathToSeach.</li> <li> <p>If you have too many <code>Pass</code> results you can filter the output to only fails by using <code>-Outcome Fail</code>.   For example:</p> <pre><code>$files | Invoke-PSRule -Path $rulePath -Outcome Fail\n</code></pre> </li> </ul>"},{"location":"quickstart/standalone-rule/#scenario-test-for-service-status","title":"Scenario - Test for service status","text":"<p> v2.0.0</p> <p>In our quickstart scenario, we have been tasked to:</p> <ul> <li>Find any services that are set to start automatically with <code>StartType</code> beginning with <code>Automatic</code>.</li> <li>Fail for any service with a <code>Status</code> other than <code>Running</code>.</li> </ul> <p>We will be using the following PowerShell code to get a list of local services.</p> PowerShell<pre><code>$services = Get-Service\n</code></pre> <p>Note</p> <p>This scenario is designed for Windows clients. The PowerShell cmdlet <code>Get-Service</code> is only available on Windows.</p>"},{"location":"quickstart/standalone-rule/#define-a-selector","title":"Define a selector","text":"<p>A selector can be used to filter a list of all services to only services that are set to start automatically. Selectors use YAML or JSON expressions and are similar to rules in many ways. A selector determines if the rule will be run or skipped.</p> <ul> <li>If the selector is <code>true</code> then the rule will be run and either pass or fail.</li> <li>If the selector is <code>false</code> then the rule will be skipped.</li> </ul> YAMLJSON <p>Create the <code>Service.Rule.yaml</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>Service.Rule.yaml</code>.</p> YAML<pre><code>---\n# Synopsis: Find services with an automatic start type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.IsAutomaticService\nspec:\n  if:\n    field: StartType\n    startsWith: Automatic\n    convert: true\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your selector in a line comment above your rule.</li> <li>Name your selector with a unique name <code>Yaml.IsAutomaticService</code>.</li> <li>The <code>if</code> property determines if PSRule will evaluate the service rule.     Specifically, the <code>StartType</code> property of each service object will be compared.     The value of <code>StartType</code> must start with <code>Automatic</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>StartType</code> to a string.</li> </ol> <p>Create the <code>Service.Rule.jsonc</code> file with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you save <code>Service.Rule.jsonc</code>.</p> JSON<pre><code>[\n    {\n        // Synopsis: Find services with an automatic start type.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Selector\",\n        \"metadata\": {\n            \"name\": \"Json.IsAutomaticService\"\n        },\n        \"spec\": {\n            \"if\": {\n                \"field\": \"StartType\",\n                \"startsWith\": \"Automatic\",\n                \"convert\": true\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your selector in a line comment above your rule.</li> <li>Name your selector with a unique name <code>Json.IsAutomaticService</code>.</li> <li>The <code>if</code> property determines if PSRule will evaluate the service rule.     Specifically, the <code>StartType</code> property of each service object will be compared.     The value of <code>StartType</code> must start with <code>Automatic</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>StartType</code> to a string.</li> </ol>"},{"location":"quickstart/standalone-rule/#define-the-service-rule","title":"Define the service rule","text":"<p>Similar to the selector, the <code>Status</code> field will be tested to determine if the service is <code>Running</code>.</p> YAMLJSONPowerShell <p>Append the following contents to the existing <code>Service.Rule.yaml</code> file.</p> YAML<pre><code>---\n# Synopsis: Automatic services should be running.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n  name: Yaml.ServiceStarted\nspec:\n  with:\n  - Yaml.IsAutomaticService\n  condition:\n    field: Status\n    equals: Running\n    convert: true\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Yaml.ServiceStarted</code>.</li> <li>The <code>with</code> property indicates to only run this rule on selected service objects.     The <code>Yaml.IsAutomaticService</code> selector must first return <code>true</code> otherwise this rule will be skipped.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each service.     Specifically, the <code>Status</code> property will be compared.     The value of <code>Status</code> must be <code>Running</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>Status</code> to a string.</li> </ol> <p>Update the contents of <code>Service.Rule.jsonc</code> to the following.</p> JSON<pre><code>[\n    {\n        // Synopsis: Find services with an automatic start type.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Selector\",\n        \"metadata\": {\n            \"name\": \"Json.IsAutomaticService\"\n        },\n        \"spec\": {\n            \"if\": {\n                \"field\": \"StartType\",\n                \"startsWith\": \"Automatic\",\n                \"convert\": true\n            }\n        }\n    },\n    {\n        // Synopsis: Automatic services should be running.\n        \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n        \"kind\": \"Rule\",\n        \"metadata\": {\n            \"name\": \"Json.ServiceStarted\"\n        },\n        \"spec\": {\n            \"with\": [\n                \"Json.IsAutomaticService\"\n            ],\n            \"condition\": {\n                \"field\": \"Status\",\n                \"equals\": \"Running\",\n                \"convert\": true\n            }\n        }\n    }\n]\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>Json.ServiceStarted</code>.</li> <li>The <code>with</code> property indicates to only run this rule on selected service objects.     The <code>Json.IsAutomaticService</code> selector must first return <code>true</code> otherwise this rule will be skipped.</li> <li>The <code>condition</code> property determines the checks PSRule will use to test each service.     Specifically, the <code>Status</code> property will be compared.     The value of <code>Status</code> must be <code>Running</code>.</li> <li>The <code>convert</code> property automatically converts the enum type of <code>Status</code> to a string.</li> </ol> <p>Create the <code>Service.Rule.ps1</code> file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you save <code>Service.Rule.ps1</code>.</p> PowerShell<pre><code># Synopsis: Automatic services should be running.\nRule 'PS.ServiceStarted' -With 'Yaml.IsAutomaticService' {\n    $status = $TargetObject.Status.ToString()\n    $Assert.HasFieldValue($status, '.', 'Running')\n}\n</code></pre> <ol> <li>Use a short <code>Synopsis:</code> to describe your rule in a line comment above your rule.     This will be shown in output as the default recommendation.     For this to be interpreted by PSRule, only a single line is allowed.</li> <li>Name your rule with a unique name <code>PS.ServiceStarted</code>.</li> <li>The <code>-With</code> parameter indicates to only run this rule on selected service objects.     The <code>Yaml.IsAutomaticService</code> selector must first return <code>true</code> otherwise this rule will be skipped.</li> <li>The condition contained within the curly braces <code>{ }</code> determines the checks PSRule will use to test each service object.</li> <li>The <code>Status</code> enum property is converted to a string.</li> <li>The <code>$Assert.HasFieldValue</code> method checks the converted <code>Status</code> property is set to <code>Running</code>.</li> </ol>"},{"location":"quickstart/standalone-rule/#testing-service-objects","title":"Testing service objects","text":"<p>You can test the rule with service object by using the <code>Invoke-PSRule</code> command. For example:</p> PowerShell<pre><code>$services = Get-Service\n\n# The directory path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\'\n\n# Test the rule\n$services | Invoke-PSRule -Path $rulePath\n</code></pre> <p>After running <code>Invoke-PSRule</code> you will get output which include for services that start automatically. Services that are <code>Running</code> should pass whereas other stopped services should fail. For manual or disabled services a warning will be generated indicating that no matching rules were found.</p> <p>For example:</p> Output<pre><code>   TargetName: edgeupdate\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nPS.ServiceStarted                   Fail       Automatic services should be running.\nYaml.ServiceStarted                 Fail       Automatic services should be running.\nJson.ServiceStarted                 Fail       Automatic services should be running.\n\n\n   TargetName: EventLog\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nPS.ServiceStarted                   Pass       Automatic services should be running.\nYaml.ServiceStarted                 Pass       Automatic services should be running.\nJson.ServiceStarted                 Pass       Automatic services should be running.\n\nWARNING: Target object 'TermService' has not been processed because no matching rules were found.\n</code></pre> <p>Tip</p> <p>You can disable the warning by setting Execution.UnprocessedObject option. Alternatively you can ignore all warnings by using the <code>-WarningAction SilentlyContinue</code> parameter.</p>"},{"location":"scenarios/","title":"Getting started with PSRule","text":""},{"location":"scenarios/#define-a-rule","title":"Define a rule","text":"<p>To define a rule, use a <code>Rule</code> block saved to a file with the <code>.Rule.ps1</code> extension.</p> <pre><code>Rule 'NameOfRule' {\n    # Rule conditions\n}\n</code></pre> <p>Within the body of the rule provide one or more conditions. A condition is valid PowerShell that results in <code>$True</code> or <code>$False</code>.</p> <p>For example:</p> <pre><code>Rule 'isFruit' {\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre> <p>An optional result message can be added to by using the <code>Recommend</code> keyword.</p> <pre><code>Rule 'isFruit' {\n    # An recommendation to display in output\n    Recommend 'Fruit is only Apple, Orange and Pear'\n\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre> <p>The rule is saved to a file named <code>isFruit.Rule.ps1</code> file. One or more rules can be defined within a single file.</p>"},{"location":"scenarios/#execute-a-rule","title":"Execute a rule","text":"<p>To execute the rule use <code>Invoke-PSRule</code>.</p> <p>For example:</p> <pre><code># Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\n</code></pre> <p>The output of this example is:</p> <pre><code>   TargetName: Fridge\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Fail       Fruit is only Apple, Orange and Pear\n\n\n   TargetName: Apple\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nisFruit                             Pass       Fruit is only Apple, Orange and Pear\n</code></pre>"},{"location":"scenarios/#additional-options","title":"Additional options","text":"<p>To filter results to only non-fruit results, use <code>Invoke-PSRule -Outcome Fail</code>. Passed, failed and error results are shown by default.</p> <pre><code># Only show non-fruit results\n$items | Invoke-PSRule -Outcome Fail;\n</code></pre> <p>For a summary of results for each rule use <code>Invoke-PSRule -As Summary</code>.</p> <p>For example:</p> <pre><code># Show rule summary\n$items | Invoke-PSRule -As Summary;\n</code></pre> <p>The output of this example is:</p> <pre><code>RuleName                            Pass  Fail  Outcome\n--------                            ----  ----  -------\nisFruit                             1     1     Fail\n</code></pre> <p>An optional failure reason can be added to the rule block by using the <code>Reason</code> keyword.</p> <pre><code>Rule 'isFruit' {\n    # An recommendation to display in output\n    Recommend 'Fruit is only Apple, Orange and Pear'\n\n    # An failure reason to display for non-fruit\n    Reason \"$($PSRule.TargetName) is not fruit.\"\n\n    # Condition to determine if the object is fruit\n    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n</code></pre> <p>To include the reason with output use <code>Invoke-PSRule -OutputFormat Wide</code>.</p> <p>For example:</p> <pre><code># Show failure reason for failing results\n$items | Invoke-PSRule -OutputFormat Wide;\n</code></pre> <p>The output of this example is:</p> <pre><code>   TargetName: Fridge\n\nRuleName                            Outcome    Reason                              Recommendation\n--------                            -------    ------                              --------------\nisFruit                             Fail       Fridge is not fruit.                Fruit is only Apple, Orange and Pear\n\n\n   TargetName: Apple\n\nRuleName                            Outcome    Reason                              Recommendation\n--------                            -------    ------                              --------------\nisFruit                             Pass                                           Fruit is only Apple, Orange and Pear\n</code></pre> <p>The final rule is saved to <code>isFruit.Rule.ps1</code>.</p>"},{"location":"scenarios/#scenarios","title":"Scenarios","text":"<p>For walk through examples of PSRule usage see:</p> <ul> <li>Validate Azure resource configuration</li> <li>Validate Azure resources tags</li> <li>Validate Kubernetes resources</li> <li>Using within continuous integration</li> <li>Packaging rules in a module</li> <li>Writing rule help</li> </ul>"},{"location":"scenarios/azure-resources/azure-resources/","title":"Validate Azure resource configuration","text":"<p>PSRule makes it easy to validate Infrastructure as Code (IaC) such as Azure resources. For example, Azure resources can be validated to match an internal standard or baseline.</p> <p>Note</p> <p>A pre-built module to validate Azure resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.</p> <p>Consider using or contributing these pre-built rule modules instead:</p> <ul> <li>PSRule.Rules.Azure</li> <li>PSRule.Rules.CAF</li> </ul> <p>This scenario covers the following:</p> <ul> <li>Defining a basic rule.</li> <li>Adding a recommendation.</li> <li>Using script pre-conditions.</li> <li>Using helper functions.</li> </ul> <p>In this scenario we will use a JSON file:</p> <ul> <li><code>resources.json</code> - An export for the Azure resource properties saved for offline use.</li> </ul> <p>To generate a similar <code>resources.json</code> file of your own, the use following command.</p> <pre><code># Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path .\\resources.json;\n</code></pre> <p>For this example we ran this command:</p> <pre><code>Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path docs/scenarios/azure-resources/resources.json;\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#define-rules","title":"Define rules","text":"<p>To validate our Azure resources we need to define some rules. Rules are defined by using the <code>Rule</code> keyword in a file ending with the <code>.Rule.ps1</code> extension.</p> <p>So start we are going to define a <code>storageAccounts.UseHttps</code> rule, which will validate that Azure Storage resources have a Secure Transfer Required enabled.</p> <p>In the example below:</p> <ul> <li>We use <code>storageAccounts.UseHttps</code> directly after the <code>Rule</code> keyword to name the rule definition. Each rule must be named uniquely.</li> <li>The <code># Synopsis:</code> comment is used to add additional metadata interpreted by PSRule.</li> <li>One or more conditions are defined within the curly braces <code>{ }</code>.</li> <li>The rule definition is saved within a file named <code>storageAccounts.Rule.ps1</code>.</li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n    # Rule conditions go here\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#set-rule-condition","title":"Set rule condition","text":"<p>Conditions can be any valid PowerShell expression that results in a <code>$True</code> or <code>$False</code>, just like an <code>If</code> statement, but without specifically requiring the <code>If</code> keyword to be used.</p> <p>Several PSRule keywords such as <code>Exists</code> and <code>AllOf</code> can supplement PowerShell to quickly build out rules that are easy to read.</p> <p>In <code>resources.json</code> one of our example storage accounts has a property <code>Properties.supportsHttpsTrafficOnly</code> as shown below, which will be how our rule will pass <code>$True</code> or fail <code>$False</code> Azure resources that we throw at it.</p> <pre><code>{\n    \"Name\": \"storage\",\n    \"ResourceName\": \"storage\",\n    \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n    \"Kind\": \"Storage\",\n    \"ResourceGroupName\": \"test-rg\",\n    \"Location\": \"eastus2\",\n    \"Properties\": {\n        \"supportsHttpsTrafficOnly\": false\n    }\n}\n</code></pre> <p>In the example below:</p> <ul> <li>We use the <code>$TargetObject</code> variable to get the object on the pipeline and access it's properties.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the object passed the validation check</li> <li><code>$False</code> - the object failed the validation check</li> </ul> </li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n    # This property returns true or false, so nothing more needs to be done\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n\n    # Alternatively this could be written as:\n    # $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#add-rule-recommendation","title":"Add rule recommendation","text":"<p>Additionally to provide feedback to the person or process running the rules, we can use the <code>Recommend</code> keyword to set a message that appears in results.</p> <p>If a recommend message is not provided the synopsis will be used instead.</p> <p>In the example below:</p> <ul> <li>Directly after the <code>Recommend</code> keyword is a message to help understand why the rule failed or passed.</li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#filter-with-preconditions","title":"Filter with preconditions","text":"<p>So far our rule works for a Storage Account, but there are many type of resources that could be returned by calling <code>Get-AzResource</code>. Most of these resources won't have the <code>Properties.supportsHttpsTrafficOnly</code> property, and if it did, it may use different configuration options instead of just <code>true</code> and <code>false</code>. This is where preconditions help out.</p> <p>Preconditions can be specified by using the <code>-If</code> parameter when defining a rule. When the rule is executed, if the precondition is <code>$True</code> then the rule is processed, otherwise it is skipped.</p> <p>In the example below:</p> <ul> <li>A check against <code>$TargetObject.ResourceType</code> ensured that our rule is only processed for Storage Accounts.</li> </ul> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { $TargetObject.ResourceType -eq 'Microsoft.Storage/storageAccounts' } {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre> <p>Skipped rules have the outcome <code>None</code> and are not included in output by default. To include skipped rules use the <code>-Outcome All</code> parameter.</p>"},{"location":"scenarios/azure-resources/azure-resources/#execute-rules","title":"Execute rules","text":"<p>With a rule defined, the next step is to execute it. To execute rules, pipe the target object to <code>Invoke-PSRule</code>.</p> <p>For example:</p> <pre><code># Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Process resources\n$resources | Invoke-PSRule;\n</code></pre> <p>PSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:</p> <pre><code>Invoke-PSRule -InputPath .\\resources.json;\n</code></pre> <p>You will notice, we didn't specify the rule. By default PSRule will look for any <code>.Rule.ps1</code> files in the current working path.</p> <p><code>Invoke-PSRule</code> supports <code>-Path</code>, <code>-Name</code> and <code>-Tag</code> parameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.</p> <p>For this example we ran these commands:</p> <pre><code>Invoke-PSRule -Path docs/scenarios/azure-resources -InputPath docs/scenarios/azure-resources/resources.json;\n</code></pre> <p>Our output looked like this:</p> <pre><code>   TargetName: storage\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nstorageAccounts.UseHttps            Fail       Storage accounts should only allow secure traffic\n</code></pre> <p>In our case <code>storageAccounts.UseHttps</code> returns a <code>Fail</code> outcome because our storage account has <code>supportsHttpsTrafficOnly</code> = <code>false</code>, which is exactly what should happen.</p>"},{"location":"scenarios/azure-resources/azure-resources/#define-helper-functions","title":"Define helper functions","text":"<p>Using helper functions is completely optional and not required in many cases. However, you may prefer to use helper functions when rule conditions or preconditions are complex and hard to understand.</p> <p>To use helper functions use a <code>function</code> block within a file with a <code>.Rule.ps1</code> extension. Any code within <code>.Rule.ps1</code> files called by <code>Invoke-PSRule</code> will be executed, however to make it available for use within a rule, a global scope modifier must be used.</p> <p>For functions this is done by prefixing the function name with <code>global:</code>.</p> <p>For example:</p> <pre><code>function global:NameOfFunction {\n    # Function body\n}\n</code></pre> <p>In our example, we are going to define a <code>ResourceType</code> function in a file named <code>common.Rule.ps1</code>. This function will be used by preconditions to check the type of Azure resource.</p> <pre><code># A custom function to filter by resource type\nfunction global:ResourceType {\n    param (\n        [String]$ResourceType\n    )\n\n    process {\n        return $TargetObject.ResourceType -eq $ResourceType;\n    }\n}\n</code></pre> <p>Updating our existing <code>storageAccounts.UseHttps</code> rule, our rule definition becomes:</p> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n    Recommend 'Storage accounts should only allow secure traffic'\n\n    $TargetObject.Properties.supportsHttpsTrafficOnly\n}\n</code></pre>"},{"location":"scenarios/azure-resources/azure-resources/#more-information","title":"More information","text":"<ul> <li>storageAccounts.Rule.ps1 - Example rules for validating Azure Storage.</li> <li>appService.Rule.ps1 - Example rules for validating Azure App Service.</li> <li>resources.json - Offline export of Azure resources.</li> <li>common.Rule.ps1 - ResourceType helper function.</li> </ul>"},{"location":"scenarios/azure-tags/azure-tags/","title":"Azure resource tagging example","text":"<p>This is an example of how PSRule can be used to validate tags on Azure resources to match an internal tagging standard.</p> <p>This scenario covers the following:</p> <ul> <li>Defining a basic rule.</li> <li>Basic usage of <code>Exists</code>, <code>Within</code> and <code>Match</code> keywords.</li> <li>Using configuration in a rule definition.</li> <li>Setting configuration in YAML.</li> <li>Running rules with configuration.</li> </ul> <p>In this scenario we will use a JSON file:</p> <ul> <li><code>resources.json</code> - An export of Azure resource properties saved for offline use.</li> </ul> <p>To generate a similar file of your own, the use following command.</p> <pre><code># Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path .\\resources.json;\n</code></pre> <p>For this example, we ran this command:</p> <pre><code>Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path docs/scenarios/azure-resources/resources.json;\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#define-rules","title":"Define rules","text":"<p>To validate our Azure resources, we need to define some rules. Rules are defined by using the <code>Rule</code> keyword in a file ending with the <code>.Rule.ps1</code> extension.</p> <p>Our business rules for Azure resource tagging can be defined with the following dot points:</p> <ul> <li>Tag names should be easy to read and understand.</li> <li>Tag names will use lower-camel/ pascal casing.</li> <li>The following mandatory tags will be used:<ul> <li>environment: An operational environment for systems and services. Valid environments are production, testing and development.</li> <li>costCentre: A allocation account within financial systems used for charging costs to a business unit. A cost centre is a number with 5 digits and can't start with a 0.</li> <li>businessUnit: The name of the organizational unit or team that owns the application/ solution.</li> </ul> </li> </ul> <p>To start we are going to define an <code>environmentTag</code> rule, which will ensure that the environment tag exists and that the value only uses allowed values.</p> <p>In the example below:</p> <ul> <li>We use <code>environmentTag</code> directly after the <code>Rule</code> keyword to name the rule definition. Each rule must be named uniquely.</li> <li>The <code># Synopsis:</code> comment is used to add additional metadata interpreted by PSRule.</li> <li>One or more conditions are defined within the curly braces <code>{ }</code>.</li> <li>The rule definition is saved within a file named <code>azureTags.Rule.ps1</code>.</li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    # Rule conditions go here\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#check-that-tag-exists","title":"Check that tag exists","text":"<p>Conditions can be any valid PowerShell expression that results in a <code>$True</code> or <code>$False</code>, just like an <code>If</code> statement, but without specifically requiring the <code>If</code> keyword to be used.</p> <p>In <code>resources.json</code> one of our example storage accounts has the <code>Tags</code> property as shown below, this is how Azure Resource Manager stores tags for a resource. We will use this property as the basis of our rules to determine if the resource is tagged and what the tag value is.</p> <pre><code>{\n    \"Name\": \"storage\",\n    \"ResourceName\": \"storage\",\n    \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n    \"Tags\": {\n        \"role\": \"deployment\",\n        \"environment\": \"production\"\n    }\n}\n</code></pre> <p>PSRule also defines several additional keywords to supplement PowerShell. These additional keywords help to create readable rules that can be built out quickly.</p> <p>In the example below:</p> <ul> <li>We use the <code>Exists</code> keyword to check if the environment tag exists.</li> <li>The <code>-CaseSensitive</code> switch is also used to ensure that the tag name uses lowercase.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the environment tag exists.</li> <li><code>$False</code> - the environment tag does not exist.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    Exists 'Tags.environment' -CaseSensitive\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#tag-uses-only-allowed-values","title":"Tag uses only allowed values","text":"<p>In our scenario, we have three environments that our environment tag could be set to. In the next example we will ensure that only allowed environment values are used.</p> <p>In the example below:</p> <ul> <li>We use the <code>Within</code> keyword to check if the environment tag uses any of the allowed values.</li> <li>The <code>-CaseSensitive</code> switch is also used to ensure that the tag value is only a lowercase environment name.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - an allowed environment is used.</li> <li><code>$False</code> - the environment tag does not use one of the allowed values.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    Exists 'Tags.environment' -CaseSensitive\n    Within 'Tags.environment' 'production', 'test', 'development' -CaseSensitive\n}\n</code></pre> <p>Alternatively, instead of using the <code>Within</code> keyword the <code>-cin</code> operator could be used. <code>Within</code> provides additional verbose logging, however either syntax is valid.</p> <p>In the example below:</p> <ul> <li><code>$TargetObject</code> automatic variable is used to get the pipeline object being evaluated.</li> <li>We use the <code>-cin</code> operator to check the environment tag only uses allowed values.</li> <li>The <code>-cin</code> operator performs a cases sensitive match on production, test and development.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - an allowed environment is used.</li> <li><code>$False</code> - the environment tag does not use one of the allowed values.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n    Exists 'Tags.environment' -CaseSensitive\n    $TargetObject.Tags.environment -cin 'production', 'test', 'development'\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#tag-value-matches-regular-expression","title":"Tag value matches regular expression","text":"<p>For our second rule (<code>costCentreTag</code>), the costCentre tag value must be 5 numbers. We can validate this by using a regular expression.</p> <p>In the example below:</p> <ul> <li>We use the <code>Match</code> keyword to check if the costCentre tag uses a numeric only value with 5 digits, not starting with 0.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the costCentre tag value matches the regular expression.</li> <li><code>$False</code> - the costCentre tag value does not use match the regular expression.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n    Exists 'Tags.costCentre' -CaseSensitive\n    Match 'Tags.costCentre' '^([1-9][0-9]{4})$'\n}\n</code></pre> <p>An alternative way to write the rule would be to use the <code>-match</code> operator instead of the <code>Match</code> keyword. Like the <code>Within</code> keyword, the <code>Match</code> keyword provides additional verbose logging that the <code>-match</code> operator does not provide.</p> <p>In the example below:</p> <ul> <li><code>$TargetObject</code> automatic variable is used to get the pipeline object being evaluated.</li> <li>We use the <code>-match</code> operator to check the costCentre tag value matches the regular expression.</li> <li>The condition will return <code>$True</code> or <code>$False</code> back to the pipeline, where:<ul> <li><code>$True</code> - the costCentre tag value matches the regular expression.</li> <li><code>$False</code> - the costCentre tag value does not use match the regular expression.</li> </ul> </li> </ul> <pre><code># Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n    Exists 'Tags.costCentre' -CaseSensitive\n    $TargetObject.Tags.costCentre -match '^([1-9][0-9]{4})$'\n}\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#use-business-unit-name-from-configuration","title":"Use business unit name from configuration","text":"<p>For our third rule (<code>businessUnitTag</code>), the businessUnit must match a valid business unit. A list of business units will be referenced from configuration instead of hard coded in the rule.</p> <p>Configuration can be used within rule definitions by defining configuration in a YAML file then using the automatic variable <code>$Configuration</code>.</p> <p>In the example below:</p> <ul> <li>We use the <code>Within</code> keyword to check if the businessUnit tag uses any of the allowed values.</li> <li><code>allowedBusinessUnits</code> configuration value can be referenced using the syntax <code>$Configuration.allowedBusinessUnits</code>.</li> <li>The rule definition is defined in azureTags.Rule.ps1.</li> <li>YAML configuration is defined in ps-rule.yaml.</li> </ul> <p>An extract from azureTags.Rule.ps1:</p> <pre><code># Synopsis: Resource must have businessUnit tag\nRule 'businessUnitTag' {\n    Exists 'Tags.businessUnit' -CaseSensitive\n    Within 'Tags.businessUnit' $Configuration.allowedBusinessUnits\n}\n</code></pre> <p>An extract from ps-rule.yaml:</p> <pre><code># Configure business units that are allowed\nconfiguration:\n  allowedBusinessUnits:\n  - 'IT Operations'\n  - 'Finance'\n  - 'HR'\n</code></pre>"},{"location":"scenarios/azure-tags/azure-tags/#execute-rules","title":"Execute rules","text":"<p>With a rule defined, the next step is to execute it. To execute rules, pipe the target object to <code>Invoke-PSRule</code>.</p> <p>For example:</p> <pre><code># Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Evaluate each resource against tagging rules\n$resources | Invoke-PSRule -Option .\\ps-rule.yaml;\n</code></pre> <p>The <code>ps-rule.yaml</code> will automatically discovered if it exists in the current working path (i.e. <code>.\\ps-rule.yaml</code>). Alternatively it can be specified with the <code>-Option</code> parameter as show above.</p> <p>PSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:</p> <pre><code># Evaluate each resource against tagging rules\nInvoke-PSRule -InputPath .\\resources.json;\n</code></pre> <p>You will notice, we didn't specify the rule. By default PSRule will look for any <code>.Rule.ps1</code> files in the current working path.</p> <p><code>Invoke-PSRule</code> supports <code>-Path</code>, <code>-Name</code> and <code>-Tag</code> parameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.</p> <p>The <code>-Option</code> parameter allows us to specify a specific YAML configuration file to use.</p> <p>For this example, we ran these commands:</p> <pre><code># Evaluate each resource against tagging rules\nInvoke-PSRule -Path docs/scenarios/azure-tags -InputPath docs/scenarios/azure-tags/resources.json -Outcome Fail -Option docs/scenarios/azure-tags/ps-rule.yaml;\n</code></pre> <p>Our output looked like this:</p> <pre><code>   TargetName: storage\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\ncostCentreTag                       Fail       Resource must have costCentre tag\nbusinessUnitTag                     Fail       Resource must have businessUnit tag\n\n\n   TargetName: web-app\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nenvironmentTag                      Fail       Resource must have environment tag\ncostCentreTag                       Fail       Resource must have costCentre tag\n\n\n   TargetName: web-app/staging\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nenvironmentTag                      Fail       Resource must have environment tag\ncostCentreTag                       Fail       Resource must have costCentre tag\n</code></pre> <p>Any resources that don't follow the tagging standard are reported with an outcome of <code>Fail</code>.</p>"},{"location":"scenarios/azure-tags/azure-tags/#more-information","title":"More information","text":"<ul> <li>azureTags.Rule.ps1 - Example rules for validating Azure resource tagging standard rules.</li> <li>resources.json - Offline export of Azure resources.</li> <li>ps-rule.yaml - A YAML configuration file for PSRule.</li> </ul>"},{"location":"scenarios/benchmark/results-v0.17.0/","title":"Results v0.17.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.18363.778 (1909/November2018Update/19H2)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=3.1.201\n  [Host]     : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n  DefaultJob : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n</code></pre> |                   Method |       Mean |     Error |    StdDev |     Median |      Gen 0 | Gen 1 | Gen 2 |   Allocated | |------------------------- |-----------:|----------:|----------:|-----------:|-----------:|------:|------:|------------:| |                   Invoke | 111.140 ms | 2.1935 ms | 4.5786 ms | 109.312 ms |  8200.0000 |     - |     - | 16839.42 KB | |                 InvokeIf | 117.141 ms | 2.2703 ms | 2.2298 ms | 116.398 ms |  9600.0000 |     - |     - | 19980.62 KB | |               InvokeType | 108.648 ms | 0.7983 ms | 0.7467 ms | 108.584 ms |  8200.0000 |     - |     - | 16870.67 KB | |            InvokeSummary | 107.300 ms | 0.8612 ms | 0.8056 ms | 107.115 ms |  8000.0000 |     - |     - | 16784.76 KB | |                      Get |   9.003 ms | 0.0643 ms | 0.0602 ms |   9.010 ms |   140.6250 |     - |     - |   307.96 KB | |                  GetHelp |   8.902 ms | 0.0831 ms | 0.0649 ms |   8.899 ms |   140.6250 |     - |     - |   306.34 KB | |                   Within | 179.522 ms | 1.5483 ms | 1.4483 ms | 179.981 ms | 15666.6667 |     - |     - | 32400.38 KB | |               WithinBulk | 247.883 ms | 2.6279 ms | 2.1944 ms | 248.124 ms | 28500.0000 |     - |     - | 59306.73 KB | |               WithinLike | 238.815 ms | 2.5538 ms | 1.9939 ms | 239.245 ms | 29333.3333 |     - |     - | 60580.58 KB | | DefaultTargetNameBinding |   2.124 ms | 0.0214 ms | 0.0200 ms |   2.129 ms |    85.9375 |     - |     - |   179.69 KB | |  CustomTargetNameBinding |   2.463 ms | 0.0483 ms | 0.0452 ms |   2.458 ms |   179.6875 |     - |     - |      375 KB | |  NestedTargetNameBinding |   2.433 ms | 0.0370 ms | 0.0328 ms |   2.420 ms |   179.6875 |     - |     - |      375 KB |</p>"},{"location":"scenarios/benchmark/results-v0.19.0/","title":"Results v0.19.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n  [Host]     : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  40,943.5 \u03bcs |   581.23 \u03bcs |   515.25 \u03bcs |  4000.0000 | 500.0000 |     - | 16452.28 KB | |                 InvokeIf |  42,806.0 \u03bcs |   477.29 \u03bcs |   423.11 \u03bcs |  4500.0000 | 500.0000 |     - | 18703.12 KB | |               InvokeType |  40,470.1 \u03bcs |   484.16 \u03bcs |   429.19 \u03bcs |  4000.0000 | 538.4615 |     - | 16452.27 KB | |            InvokeSummary |  39,768.8 \u03bcs |   462.14 \u03bcs |   385.91 \u03bcs |  4000.0000 | 153.8462 |     - | 16397.82 KB | |                      Get |  11,145.4 \u03bcs |   402.59 \u03bcs | 1,187.03 \u03bcs |    46.8750 |        - |     - |   252.11 KB | |                  GetHelp |  10,169.1 \u03bcs |   625.02 \u03bcs | 1,842.88 \u03bcs |    46.8750 |        - |     - |   250.51 KB | |                   Within |  78,993.5 \u03bcs |   799.51 \u03bcs |   667.63 \u03bcs |  8000.0000 | 400.0000 |     - | 32791.83 KB | |               WithinBulk | 118,800.8 \u03bcs | 1,637.36 \u03bcs | 1,531.59 \u03bcs | 14333.3333 | 333.3333 |     - | 59817.29 KB | |               WithinLike | 106,796.3 \u03bcs | 2,067.20 \u03bcs | 2,538.71 \u03bcs | 11333.3333 |        - |     - | 47311.07 KB | | DefaultTargetNameBinding |     698.2 \u03bcs |     7.51 \u03bcs |     7.02 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     884.7 \u03bcs |     7.11 \u03bcs |     6.65 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     883.9 \u03bcs |    14.44 \u03bcs |    12.80 \u03bcs |    85.9375 |        - |     - |   351.56 KB |</p>"},{"location":"scenarios/benchmark/results-v0.20.0/","title":"Results v0.20.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n  [Host]     : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |     Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|------:|------------:| |                   Invoke |  42,162.8 \u03bcs |   827.36 \u03bcs | 1,263.47 \u03bcs |  3833.3333 |         - |     - |    15952 KB | |                 InvokeIf |  45,646.4 \u03bcs |   912.31 \u03bcs | 1,924.38 \u03bcs |  4416.6667 |  416.6667 |     - | 18202.98 KB | |               InvokeType |  41,825.5 \u03bcs |   810.73 \u03bcs |   901.12 \u03bcs |  3833.3333 |         - |     - |    15952 KB | |            InvokeSummary |  41,133.3 \u03bcs |   777.97 \u03bcs |   895.91 \u03bcs |  3833.3333 |  500.0000 |     - | 15897.56 KB | |                      Get |  10,054.3 \u03bcs |   396.83 \u03bcs | 1,170.07 \u03bcs |    46.8750 |         - |     - |   252.11 KB | |                  GetHelp |  10,581.4 \u03bcs |   448.15 \u03bcs | 1,321.38 \u03bcs |    46.8750 |         - |     - |   250.51 KB | |                   Within |  81,215.1 \u03bcs | 1,532.85 \u03bcs | 1,433.83 \u03bcs |  7750.0000 |  250.0000 |     - | 32290.62 KB | |               WithinBulk | 123,301.6 \u03bcs | 2,451.51 \u03bcs | 3,958.73 \u03bcs | 14000.0000 | 1000.0000 |     - | 59317.29 KB | |               WithinLike | 109,738.9 \u03bcs | 1,933.95 \u03bcs | 1,809.02 \u03bcs | 11333.3333 | 1000.0000 |     - | 46811.07 KB | | DefaultTargetNameBinding |     696.0 \u03bcs |    12.06 \u03bcs |    10.69 \u03bcs |    38.0859 |         - |     - |   156.25 KB | |  CustomTargetNameBinding |     845.6 \u03bcs |    11.75 \u03bcs |    10.42 \u03bcs |    85.9375 |         - |     - |   351.56 KB | |  NestedTargetNameBinding |     856.0 \u03bcs |    12.29 \u03bcs |    10.90 \u03bcs |    85.9375 |         - |     - |   351.56 KB |</p>"},{"location":"scenarios/benchmark/results-v0.21.0/","title":"Results v0.21.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n  [Host]     : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  41,409.3 \u03bcs |   743.11 \u03bcs | 1,089.24 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.02 KB | |                 InvokeIf |  43,138.3 \u03bcs |   510.44 \u03bcs |   426.24 \u03bcs |  4416.6667 |  83.3333 |     - | 18374.86 KB | |               InvokeType |  41,511.3 \u03bcs |   703.93 \u03bcs |   963.55 \u03bcs |  3923.0769 | 230.7692 |     - | 16144.62 KB | |            InvokeSummary |  40,319.9 \u03bcs |   795.95 \u03bcs |   705.59 \u03bcs |  3900.0000 | 500.0000 |     - | 16124.26 KB | |                      Get |   9,873.7 \u03bcs |   392.08 \u03bcs | 1,149.89 \u03bcs |    46.8750 |        - |     - |   253.44 KB | |                  GetHelp |   9,943.1 \u03bcs |   406.36 \u03bcs | 1,198.17 \u03bcs |    46.8750 |        - |     - |   251.84 KB | |                   Within |  76,627.6 \u03bcs | 1,527.91 \u03bcs | 1,759.54 \u03bcs |  7800.0000 |        - |     - | 32460.47 KB | |               WithinBulk | 115,374.0 \u03bcs | 2,279.41 \u03bcs | 3,269.07 \u03bcs | 14333.3333 |        - |     - | 59488.54 KB | |               WithinLike | 102,684.3 \u03bcs | 1,482.11 \u03bcs | 1,313.85 \u03bcs | 11500.0000 | 750.0000 |     - |  46983.1 KB | | DefaultTargetNameBinding |     673.8 \u03bcs |     4.27 \u03bcs |     3.79 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     888.9 \u03bcs |    15.31 \u03bcs |    12.78 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     901.3 \u03bcs |     9.04 \u03bcs |     8.01 \u03bcs |    85.9375 |        - |     - |   351.56 KB |</p>"},{"location":"scenarios/benchmark/results-v0.22.0/","title":"Results v0.22.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n  [Host]     : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  40,804.1 \u03bcs |   656.89 \u03bcs |   614.45 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.02 KB | |                 InvokeIf |  42,768.8 \u03bcs |   843.79 \u03bcs |   704.61 \u03bcs |  4461.5385 |  76.9231 |     - | 18374.92 KB | |               InvokeType |  40,487.0 \u03bcs |   609.33 \u03bcs | 1,034.69 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |            InvokeSummary |  40,403.1 \u03bcs |   806.53 \u03bcs |   714.97 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.26 KB | |                   Assert |  41,551.0 \u03bcs |   684.23 \u03bcs |   640.03 \u03bcs |  4000.0000 | 153.8462 |     - | 16538.36 KB | |                      Get |  10,180.9 \u03bcs |   402.29 \u03bcs | 1,186.17 \u03bcs |    46.8750 |        - |     - |   231.12 KB | |                  GetHelp |   9,941.1 \u03bcs |   409.65 \u03bcs | 1,207.87 \u03bcs |    46.8750 |        - |     - |   229.52 KB | |                   Within |  75,818.3 \u03bcs | 1,504.74 \u03bcs | 2,297.90 \u03bcs |  7800.0000 | 600.0000 |     - | 32468.28 KB | |               WithinBulk | 112,731.0 \u03bcs | 1,239.66 \u03bcs | 1,035.17 \u03bcs | 14333.3333 | 666.6667 |     - | 59496.35 KB | |               WithinLike | 101,227.7 \u03bcs | 1,990.03 \u03bcs | 2,854.05 \u03bcs | 11333.3333 |        - |     - | 46623.62 KB | | DefaultTargetNameBinding |     654.3 \u03bcs |    10.46 \u03bcs |     9.78 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     854.3 \u03bcs |    16.30 \u03bcs |    15.25 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     945.7 \u03bcs |    18.78 \u03bcs |    19.29 \u03bcs |    85.9375 |        - |     - |   351.57 KB | |      AssertHasFieldValue |   1,036.2 \u03bcs |    13.63 \u03bcs |    12.08 \u03bcs |   121.0938 |        - |     - |      500 KB |</p>"},{"location":"scenarios/benchmark/results-v0.3.0/","title":"Results v0.3.0","text":"<p><pre><code>BenchmarkDotNet=v0.11.3, OS=Windows 10.0.17763.195 (1809/October2018Update/Redstone5)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=2.2.100\n  [Host]     : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n  DefaultJob : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n</code></pre> |        Method |       Mean |     Error |    StdDev | Gen 0/1k Op | Gen 1/1k Op | Gen 2/1k Op | Allocated Memory/Op | |-------------- |-----------:|----------:|----------:|------------:|------------:|------------:|--------------------:| |        Invoke | 117.257 ms | 2.1959 ms | 2.1567 ms |   8400.0000 |    400.0000 |           - |         17355.83 KB | |      InvokeIf | 128.418 ms | 3.0122 ms | 3.8095 ms |   9750.0000 |    500.0000 |           - |         20301.73 KB | | InvokeSummary | 116.479 ms | 1.9241 ms | 1.7998 ms |   8400.0000 |           - |           - |         17301.03 KB | |           Get |   8.921 ms | 0.0864 ms | 0.0766 ms |     93.7500 |           - |           - |           203.82 KB |</p>"},{"location":"scenarios/benchmark/results-v1.0.1/","title":"Results v1.0.1","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.102\n  [Host]     : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |       Median |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-------------:|-----------:|---------:|------:|------------:| |                   Invoke |  39,343.5 \u03bcs |   781.08 \u03bcs |   835.75 \u03bcs |  39,287.2 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |                 InvokeIf |  41,264.0 \u03bcs |   545.97 \u03bcs |   483.99 \u03bcs |  41,148.4 \u03bcs |  4461.5385 |  76.9231 |     - | 18374.92 KB | |               InvokeType |  39,514.4 \u03bcs |   755.90 \u03bcs |   670.09 \u03bcs |  39,343.8 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |            InvokeSummary |  39,251.4 \u03bcs |   605.30 \u03bcs |   566.20 \u03bcs |  39,143.5 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.26 KB | |                   Assert |  40,662.2 \u03bcs |   776.24 \u03bcs |   688.12 \u03bcs |  40,589.9 \u03bcs |  4000.0000 | 333.3333 |     - | 16538.53 KB | |                      Get |   8,570.8 \u03bcs |   429.97 \u03bcs | 1,267.78 \u03bcs |   8,872.7 \u03bcs |    46.8750 |        - |     - |   231.12 KB | |                  GetHelp |   9,235.4 \u03bcs |   295.56 \u03bcs |   871.45 \u03bcs |   9,238.7 \u03bcs |    46.8750 |        - |     - |   229.52 KB | |                   Within |  75,171.4 \u03bcs |   744.98 \u03bcs |   660.41 \u03bcs |  75,223.5 \u03bcs |  7750.0000 | 750.0000 |     - | 32468.28 KB | |               WithinBulk | 110,726.9 \u03bcs | 2,142.74 \u03bcs | 2,200.44 \u03bcs | 109,801.1 \u03bcs | 14500.0000 | 500.0000 |     - | 59496.51 KB | |               WithinLike | 101,989.2 \u03bcs | 2,007.91 \u03bcs | 4,056.09 \u03bcs | 100,288.9 \u03bcs | 11250.0000 |        - |     - | 46623.25 KB | | DefaultTargetNameBinding |     626.0 \u03bcs |    11.49 \u03bcs |    10.75 \u03bcs |     622.9 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     796.3 \u03bcs |     7.48 \u03bcs |     7.00 \u03bcs |     797.0 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     806.1 \u03bcs |    12.12 \u03bcs |    10.12 \u03bcs |     805.3 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |      AssertHasFieldValue |     900.6 \u03bcs |    14.51 \u03bcs |    12.87 \u03bcs |     901.2 \u03bcs |   122.0703 |        - |     - |      500 KB |</p>"},{"location":"scenarios/benchmark/results-v1.1.0/","title":"Results v1.1.0","text":"<p><pre><code>BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.103\n  [Host]     : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |    Gen 1 | Gen 2 |   Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| |                   Invoke |  40,327.3 \u03bcs |   801.24 \u03bcs | 1,013.31 \u03bcs |  3923.0769 | 538.4615 |     - | 16124.02 KB | |                 InvokeIf |  42,943.9 \u03bcs |   849.72 \u03bcs | 1,396.11 \u03bcs |  4461.5385 |  76.9231 |     - | 18374.92 KB | |               InvokeType |  40,880.7 \u03bcs |   783.51 \u03bcs | 1,452.28 \u03bcs |  3900.0000 |        - |     - | 16149.45 KB | |            InvokeSummary |  39,101.4 \u03bcs |   431.56 \u03bcs |   336.93 \u03bcs |  3916.6667 | 500.0000 |     - | 16124.26 KB | |                   Assert |  41,917.1 \u03bcs |   831.37 \u03bcs | 1,192.33 \u03bcs |  4076.9231 | 461.5385 |     - | 16780.81 KB | |                      Get |   9,643.0 \u03bcs |   428.32 \u03bcs | 1,262.91 \u03bcs |    54.6875 |   7.8125 |     - |   231.12 KB | |                  GetHelp |   9,271.5 \u03bcs |   372.94 \u03bcs | 1,099.63 \u03bcs |    46.8750 |        - |     - |   229.52 KB | |                   Within |  76,020.5 \u03bcs |   954.22 \u03bcs |   744.99 \u03bcs |  7800.0000 | 600.0000 |     - | 32468.65 KB | |               WithinBulk | 112,135.7 \u03bcs | 2,189.72 \u03bcs | 2,342.97 \u03bcs | 14500.0000 | 500.0000 |     - | 59499.77 KB | |               WithinLike | 101,928.4 \u03bcs | 1,952.97 \u03bcs | 2,398.43 \u03bcs | 11333.3333 |        - |     - | 46623.57 KB | | DefaultTargetNameBinding |     655.6 \u03bcs |    13.11 \u03bcs |    25.87 \u03bcs |    38.0859 |        - |     - |   156.25 KB | |  CustomTargetNameBinding |     822.1 \u03bcs |    16.06 \u03bcs |    19.11 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |  NestedTargetNameBinding |     878.9 \u03bcs |    16.63 \u03bcs |    17.08 \u03bcs |    85.9375 |        - |     - |   351.56 KB | |      AssertHasFieldValue |     923.2 \u03bcs |    17.81 \u03bcs |    19.05 \u03bcs |   122.0703 |   0.9766 |     - |   500.26 KB |</p>"},{"location":"scenarios/benchmark/results-v1.10.0/","title":"Results v1.10.0","text":"<p><pre><code>BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n  [Host]     : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |     Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| |                   Invoke |  50,742.5 \u03bcs |   908.47 \u03bcs |   709.27 \u03bcs |  4100.0000 |  400.0000 | 17,758 KB | |                 InvokeIf |  53,048.6 \u03bcs |   698.34 \u03bcs |   619.06 \u03bcs |  4500.0000 |  200.0000 | 20,008 KB | |               InvokeType |  50,575.6 \u03bcs |   794.27 \u03bcs |   663.25 \u03bcs |  4000.0000 |  200.0000 | 17,760 KB | |            InvokeSummary |  50,449.0 \u03bcs |   698.80 \u03bcs |   619.47 \u03bcs |  4100.0000 |  400.0000 | 17,758 KB | |                   Assert |  52,152.6 \u03bcs |   765.95 \u03bcs |   678.99 \u03bcs |  4200.0000 |  300.0000 | 18,462 KB | |                      Get |   5,793.8 \u03bcs |    86.70 \u03bcs |    81.10 \u03bcs |    78.1250 |         - |    364 KB | |                  GetHelp |   5,799.6 \u03bcs |    76.72 \u03bcs |    71.77 \u03bcs |    85.9375 |    7.8125 |    364 KB | |                   Within |  89,538.2 \u03bcs | 1,754.26 \u03bcs | 1,555.11 \u03bcs |  8000.0000 | 1000.0000 | 34,102 KB | |               WithinBulk | 128,126.9 \u03bcs | 1,928.80 \u03bcs | 1,709.83 \u03bcs | 14666.6667 | 1333.3333 | 61,131 KB | |               WithinLike | 112,174.1 \u03bcs | 1,132.30 \u03bcs | 1,003.76 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding |     695.6 \u03bcs |    13.57 \u03bcs |    14.52 \u03bcs |    38.0859 |         - |    156 KB | |  CustomTargetNameBinding |     851.0 \u03bcs |    10.35 \u03bcs |     8.64 \u03bcs |    85.9375 |         - |    352 KB | |  NestedTargetNameBinding |     961.5 \u03bcs |    17.83 \u03bcs |    15.80 \u03bcs |    85.9375 |         - |    352 KB | |      AssertHasFieldValue |   3,033.5 \u03bcs |    60.15 \u03bcs |    66.85 \u03bcs |   253.9063 |    7.8125 |  1,040 KB |</p>"},{"location":"scenarios/benchmark/results-v1.11.0/","title":"Results v1.11.0","text":"<p><pre><code>BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n  [Host]     : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n</code></pre> |                   Method |         Mean |       Error |      StdDev |      Gen 0 |     Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| |                   Invoke |  50,529.4 \u03bcs | 1,006.40 \u03bcs |   941.38 \u03bcs |  4000.0000 |  444.4444 | 17,758 KB | |                 InvokeIf |  51,974.4 \u03bcs |   667.26 \u03bcs |   591.51 \u03bcs |  4500.0000 |  200.0000 | 20,008 KB | |               InvokeType |  49,901.2 \u03bcs |   679.83 \u03bcs |   567.69 \u03bcs |  4000.0000 |  363.6364 | 17,758 KB | |            InvokeSummary |  51,198.9 \u03bcs |   862.22 \u03bcs |   922.57 \u03bcs |  4000.0000 |  363.6364 | 17,758 KB | |                   Assert |  52,136.6 \u03bcs |   588.93 \u03bcs |   550.88 \u03bcs |  4100.0000 |  300.0000 | 18,461 KB | |                      Get |   5,710.0 \u03bcs |   111.69 \u03bcs |   104.47 \u03bcs |    85.9375 |    7.8125 |    364 KB | |                  GetHelp |   5,777.4 \u03bcs |    97.83 \u03bcs |    91.51 \u03bcs |    85.9375 |    7.8125 |    364 KB | |                   Within |  88,106.3 \u03bcs | 1,752.66 \u03bcs | 1,799.86 \u03bcs |  8000.0000 | 1000.0000 | 34,102 KB | |               WithinBulk | 125,319.9 \u03bcs | 2,303.80 \u03bcs | 2,154.98 \u03bcs | 14666.6667 | 1000.0000 | 61,133 KB | |               WithinLike | 115,376.3 \u03bcs | 1,866.04 \u03bcs | 1,654.20 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding |     669.5 \u03bcs |     6.52 \u03bcs |     6.10 \u03bcs |    38.0859 |         - |    156 KB | |  CustomTargetNameBinding |     837.6 \u03bcs |     6.70 \u03bcs |     6.27 \u03bcs |    85.9375 |         - |    352 KB | |  NestedTargetNameBinding |     854.1 \u03bcs |     9.50 \u03bcs |     7.42 \u03bcs |    85.9375 |         - |    352 KB | |      AssertHasFieldValue |   2,967.0 \u03bcs |    38.88 \u03bcs |    34.47 \u03bcs |   253.9063 |    7.8125 |  1,040 KB |</p>"},{"location":"scenarios/benchmark/results-v2.0.0/","title":"Results v2.0.0","text":"<p><pre><code>BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=6.0.400\n  [Host]     : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\n  DefaultJob : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\n</code></pre> |                   Method |             Mean |           Error |           StdDev |           Median |      Gen 0 |     Gen 1 | Allocated | |------------------------- |-----------------:|----------------:|-----------------:|-----------------:|-----------:|----------:|----------:| |                   Invoke |  71,586,583.6 ns | 4,077,161.43 ns | 11,957,608.68 ns |  71,526,200.0 ns |  4200.0000 |  600.0000 | 17,703 KB | |                 InvokeIf |  59,661,136.5 ns | 1,161,506.18 ns |  1,192,781.33 ns |  59,397,680.0 ns |  4400.0000 |  400.0000 | 19,954 KB | |               InvokeType |  55,089,186.0 ns | 1,045,769.22 ns |  1,989,684.63 ns |  54,242,620.0 ns |  4300.0000 |  500.0000 | 17,703 KB | |            InvokeSummary |  55,371,580.7 ns | 1,271,559.50 ns |  3,586,456.14 ns |  53,815,745.0 ns |  4300.0000 |  500.0000 | 17,704 KB | |                   Assert |  56,146,053.8 ns | 1,122,221.08 ns |  3,053,085.20 ns |  54,841,105.0 ns |  4500.0000 |  600.0000 | 18,407 KB | |                      Get |   5,701,341.2 ns |   110,332.76 ns |    158,235.95 ns |   5,665,673.8 ns |    78.1250 |    7.8125 |    365 KB | |                  GetHelp |   5,750,066.9 ns |   113,595.72 ns |    170,024.73 ns |   5,720,298.0 ns |    85.9375 |    7.8125 |    366 KB | |                   Within |  99,151,338.5 ns | 2,136,858.10 ns |  6,165,324.21 ns |  97,015,516.7 ns |  8333.3333 | 1333.3333 | 34,142 KB | |               WithinBulk | 147,062,385.7 ns | 2,633,709.47 ns |  2,334,714.85 ns | 146,838,450.0 ns | 14000.0000 | 3000.0000 | 61,169 KB | |               WithinLike | 120,988,346.7 ns | 2,099,294.17 ns |  1,963,681.06 ns | 120,963,000.0 ns | 11666.6667 | 1666.6667 | 48,297 KB | | DefaultTargetNameBinding |     731,969.9 ns |    13,918.54 ns |     36,422.40 ns |     714,067.8 ns |    38.0859 |         - |    156 KB | |  CustomTargetNameBinding |   1,052,297.9 ns |    44,284.38 ns |    125,627.41 ns |   1,022,416.2 ns |    85.9375 |         - |    352 KB | |  NestedTargetNameBinding |     916,580.7 ns |    24,378.48 ns |     71,497.85 ns |     903,449.3 ns |    85.9375 |         - |    352 KB | |      AssertHasFieldValue |   3,082,706.1 ns |    61,644.86 ns |     68,518.10 ns |   3,058,487.1 ns |   234.3750 |         - |    962 KB | |             PathTokenize |         846.6 ns |        16.52 ns |         23.69 ns |         842.4 ns |     0.2632 |         - |      1 KB | |      PathExpressionBuild |         548.3 ns |        10.14 ns |         11.68 ns |         547.1 ns |     0.3500 |         - |      1 KB | |        PathExpressionGet |     356,089.5 ns |     7,027.54 ns |     11,348.18 ns |     351,085.5 ns |    17.0898 |         - |     70 KB |</p>"},{"location":"scenarios/containers/container-execution/","title":"Using PSRule from a Container","text":"<p>Depending on your development or CI/CD process for your environment you may desire to use PSRules to validate your Infrastructure as Code (IaC) from a container. This document shows how you can use a simple container based on the mcr.microsoft.com/powershell image from Microsoft.</p> <p>In this tutorial we are going to use a simple Ubuntu based PowerShell image to validate an ARM template. We will do this by creating a dockerfile to describe and create a container image that we can then run. When we run the container we will use a volume mount to share our ARM template and test code for the container to then execute the PSRule for Azure against our ARM template and output the results.</p>"},{"location":"scenarios/containers/container-execution/#creating-the-image","title":"Creating the image","text":"<p>Creating an image ready to run PSRules first requires a dockerfile. The below example will use the latest PowerShell image released and install the <code>PSRule</code> and <code>PSRule.Rules.Azure</code> modules.</p> Dockerfile<pre><code># Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\nFROM mcr.microsoft.com/powershell:7.2-ubuntu-22.04\nSHELL [\"pwsh\", \"-command\"]\n\nRUN Install-Module -Name 'PSRule','PSRule.Rules.Azure' -Force\n</code></pre> <p>The below docker command can be used to create the image locally.</p> <pre><code>docker build --tag psrule:latest .\n</code></pre> <p>Note</p> <p>While fine for an example, it is common to always reference a container by a version number and not the <code>latest</code> tag. Using the <code>latest</code> tag may lead to unexpected behavior as version changes occur.</p>"},{"location":"scenarios/containers/container-execution/#create-your-test-script","title":"Create your test script","text":"<p>Create a new directory and add a new file named <code>validate-files.ps1</code>. This file will run the PSRule test for us on our new container image. Add the below code to the file.</p> <pre><code># Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\n&lt;#\n    .SYNOPSIS\n        Create a PSRule AzRuleTemplate data file and run the PSRule.Rules.Azure module rules against the output.\n#&gt;\n\nGet-AzRuleTemplateLink \"$PSScriptRoot/template\" | Export-AzRuleTemplateData -OutputPath \"$PSScriptRoot/out\"\n\nAssert-PSRule -InputPath \"$PSScriptRoot/out/\" -Module 'PSRule.Rules.Azure' -As Summary\n</code></pre> <p>Also, within the new directory add another directory named <code>template</code>. Add any ARM template you would like to test in this directory. For a starting point you can get a template from Azure Quickstart Templates.</p> <p>Your directory should now look like the below.</p> <pre><code>- Directory \n  |--&gt; validate-files.ps1\n  |--&gt; template\n    |--&gt; ARM template...\n</code></pre>"},{"location":"scenarios/containers/container-execution/#run-psrules-in-the-container","title":"Run PSRules in the container","text":"<p>Now we are ready to go! Run the below docker command to test the ARM template.</p> <pre><code>docker run -it --rm -v $PWD/:/src psrule:latest pwsh -file /src/validate-files.ps1\n</code></pre> <p>This command runs the container and the PSRule tests by mounting the directory to the <code>/src</code> path and then executing the <code>validate-files.ps1</code> script.</p> <p>Note</p> <p>The volume mount option expects your current working directory to be the new directory created. You can change this to an absolute or relative path if desired.</p>"},{"location":"scenarios/containers/container-execution/#clean-up","title":"Clean up","text":"<p>When you are ready to clean up the container image you can do so with the below command.</p> <pre><code>docker image rm psrule\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/","title":"Kubernetes resource validation example","text":"<p>This is an example of how PSRule can be used to validate Kubernetes resources to match an internal metadata and configuration standard.</p> <p>Note</p> <p>A pre-built module to validate Kubernetes resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.</p> <p>Consider using or contributing these pre-built rule modules instead:</p> <ul> <li>PSRule.Rules.Kubernetes</li> </ul> <p>This scenario covers the following:</p> <ul> <li>Defining a basic rule.</li> <li>Configuring custom binding.</li> <li>Using a type precondition.</li> <li>Running rules using YAML input.</li> </ul> <p>In this scenario we will use a YAML file:</p> <ul> <li><code>resources.yaml</code> - A Kubernetes manifest containing deployments and services.</li> </ul>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#define-rules","title":"Define rules","text":"<p>To validate our Kubernetes resources, we need to define some rules. Rules are defined by using the <code>Rule</code> keyword in a file ending with the <code>.Rule.ps1</code> extension.</p> <p>Our business rules for configuration Kubernetes resources can be defined with the following dot points:</p> <ul> <li>The following recommended labels will be used on all services and deployments:<ul> <li><code>app.kubernetes.io/name</code> - the name of the application/ service.</li> <li><code>app.kubernetes.io/version</code> - the version of the service.</li> <li><code>app.kubernetes.io/component</code> - identifies the type of component, valid options are <code>web</code>, <code>api</code>, <code>database</code> and <code>gateway</code></li> </ul> </li> <li>For <code>web</code> or <code>api</code> deployments, a minimum of two (2) replicas must be used.</li> <li>Deployments must use container images with a specific version tag, and not <code>latest</code>.</li> <li>Deployments must declare minimum and maximum memory/ CPU resources.</li> </ul> <p>In the example below:</p> <ul> <li>We use <code>metadata.Name</code> directly after the <code>Rule</code> keyword to name the rule definition. Each rule must be named uniquely.</li> <li>The <code># Synopsis:</code> comment is used to add additional metadata interpreted by PSRule.</li> <li>One or more conditions are defined within the curly braces <code>{ }</code>.</li> <li>The rule definition is saved within a file named <code>kubernetes.Rule.ps1</code>.</li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n    # Rule conditions go here\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#check-that-the-label-exists","title":"Check that the label exists","text":"<p>In the next step, we define one or more conditions.</p> <p>Conditions can be:</p> <ul> <li>Any valid PowerShell that returns a true (pass) when the condition is met or false (fail) when the condition is not met.</li> <li>More than one condition can be defined, if any condition returns false then the whole rule fails.</li> </ul> <p>PSRule includes several convenience keywords such as <code>AllOf</code>, <code>AnyOf</code>, <code>Exists</code>, <code>Match</code>, <code>TypeOf</code> and <code>Within</code> that make conditions faster to define, easier to understand and troubleshoot. However, use of these keywords is optional.</p> <p>In the example below:</p> <ul> <li>We use the <code>Exists</code> keyword to check that the resource has the <code>app.kubernetes.io/name</code> label set.<ul> <li>By default, PSRule will step through nested properties separated by a <code>.</code>. i.e. <code>labels</code> is a property of <code>metadata</code>.</li> <li>Kubernetes supports and recommends label namespaces, which often use <code>.</code> in their name. PSRule supports this by enclosing the field name (<code>app.kubernetes.io/name</code>) in apostrophes (<code>'</code>) so that <code>app.kubernetes.io/name</code> is checked instead of <code>app</code>.</li> </ul> </li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>We have also defined something similar for the version and component labels.</p> <p>In the example below:</p> <ul> <li>Double apostrophes (<code>''</code>) are used to enclose <code>app.kubernetes.io/name</code> because the field name uses <code>'</code> at the start and end of the string instead of <code>\"</code> in the previous example.</li> <li>The <code>Within</code> keyword is used to validate that the <code>app.kubernetes.io/component</code> only uses one of four (4) allowed values.</li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/version label\nRule 'metadata.Version' {\n    Exists 'metadata.labels.''app.kubernetes.io/version'''\n}\n\n# Synopsis: Must have the app.kubernetes.io/component label\nRule 'metadata.Component' {\n    Exists 'metadata.labels.''app.kubernetes.io/component'''\n    Within 'metadata.labels.''app.kubernetes.io/component''' 'web', 'api', 'database', 'gateway' -CaseSensitive\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#use-custom-binding","title":"Use custom binding","text":"<p>Before processing rules, PSRule binds <code>TargetName</code> and <code>TargetType</code> properties to the pipeline object. These properties are used for filtering and displaying results.</p> <p>The default properties that PSRule binds are different from how Kubernetes resources are structured. Kubernetes uses:</p> <ul> <li><code>metadata.name</code> to store the name of a resource.</li> <li><code>kind</code> to store the type of resource.</li> </ul> <p>The default bindings can be updated by providing custom property names or a custom script. To change binding property names set the <code>Binding.TargetName</code> and <code>Binding.TargetType</code> configuration options.</p> <p>The following example shows how to set the options using a YAML configuration file:</p> <ul> <li>TargetName is bound to <code>metadata.name</code></li> <li>TargetType is bound to <code>kind</code></li> </ul> <pre><code>binding:\n  targetName:\n  - metadata.name\n  targetType:\n  - kind\n</code></pre> <p>These options can be set in the file <code>.\\ps-rule.yaml</code> to be automatically loaded at when PSRule cmdlets are called. To set these configuration options either edit the file manually or use the following command.</p> <pre><code># Set options in ps-rule.yaml\nSet-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\n</code></pre> <p>Alternatively, these options can be set at runtime using the hashtable syntax.</p> <pre><code># Save options to a variable\n$option = New-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\n</code></pre> <p>These options will be passed to <code>Invoke-PSRule</code> using the <code>-Option</code> parameter in a later step.</p>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#define-preconditions","title":"Define preconditions","text":"<p>Currently the <code>metadata.Name</code> rule defined in a previous step will be executed for any type of object. Kubernetes has many types of built-in resource such as Services, Deployments, Namespaces, Pods and ClusterRoles.</p> <p>By defining a precondition, we can ensure that the rule is only processed for Services or Deployments to match our business rules.</p> <p>PSRule supports two types of preconditions, either type (<code>-Type</code>) or script block (<code>-If</code>).</p> <ul> <li>Type preconditions are one or more type names that PSRule compares to the <code>TargetType</code> binding, where:<ul> <li>One of the type names names equal <code>TargetType</code> the rule will be processed.</li> <li>None of the type names equal <code>TargetType</code> the rule be skipped.</li> </ul> </li> <li>Script block preconditions is a PowerShell script block that returns true or false, where:<ul> <li>True - Continue processing the rule.</li> <li>False - Skip processing the rule.</li> </ul> </li> </ul> <p>Preconditions are evaluated once per rule for each object.</p> <p>In the example below:</p> <ul> <li>We update our <code>metadata.Name</code> rule to use the <code>-Type</code> parameter to specify a type precondition of either Deployment or Service.</li> <li>In a previous step, <code>TypeName</code> was bound to the <code>kind</code> property which will be Deployment or Service for these resource types.</li> </ul> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre> <p>Using a type precondition satisfies our business rules and will deliver faster performance then using a script block. An example using a script block precondition is also shown below.</p> <pre><code># Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -If { $TargetObject.kind -eq 'Deployment' -or $TargetObject.kind -eq 'Service' } {\n    Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#complete-remaining-rules","title":"Complete remaining rules","text":"<p>The remaining rule definitions from our defined business rules are included below. Each follows a similar pattern and builds on the previous sections.</p> <p>In the example below:</p> <ul> <li>The built-in variable <code>$TargetObject</code> is used to get the current pipeline object.<ul> <li>Built-in keywords like <code>Exists</code> automatically default to <code>$TargetObject</code>, but can be piped alternative input as shown in the rule definition named <code>deployment.ResourcesSet</code>.</li> </ul> </li> </ul> <pre><code># Synopsis: Deployments use a minimum of 2 replicas\nRule 'deployment.HasMinimumReplicas' -Type 'Deployment' {\n    Exists 'spec.replicas'\n    $TargetObject.spec.replicas -ge 2\n}\n\n# Synopsis: Deployments use specific tags\nRule 'deployment.NotLatestImage' -Type 'Deployment' {\n    foreach ($container in $TargetObject.spec.template.spec.containers) {\n        $container.image -like '*:*' -and\n        $container.image -notlike '*:latest'\n    }\n}\n\n# Synopsis: Resource requirements are set for each container\nRule 'deployment.ResourcesSet' -Type 'Deployment' {\n    foreach ($container in $TargetObject.spec.template.spec.containers) {\n        $container | Exists 'resources.requests.cpu'\n        $container | Exists 'resources.requests.memory'\n        $container | Exists 'resources.limits.cpu'\n        $container | Exists 'resources.limits.memory'\n    }\n}\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#execute-rules","title":"Execute rules","text":"<p>With some rules defined, the next step is to execute them. For this example, we'll use <code>Invoke-PSRule</code> to get the result for each rule. The <code>Test-PSRuleTarget</code> cmdlet can be used if only a true or false is required.</p> <p>In our example we are using the YAML format to store Kubernetes resources. PSRule has built-in support for YAML so we can import these files directly from disk or process output from a command such as <code>kubectl</code>.</p> <p>In the examples below:</p> <ul> <li>The <code>-InputPath</code> parameter is used to load objects from disk as YAML. YAML is automatically detected based on the <code>.yaml</code> file extension. Alternatively the <code>-Foramt Yaml</code> parameter can be used.</li> <li>Binding parameters are read from <code>ps-rule.yaml</code> in the current working path. Alternatively the <code>-Option</code> parameter could be used to specify an alternative file path.</li> <li><code>kubectl</code> is called with the <code>-o yaml</code> to output resources as YAML.</li> <li><code>kubectl</code> is piped to <code>Out-String</code> to convert the multi-line output to a single string.</li> <li>The <code>-Format</code> parameter informs PSRule that the string is YAML and it should convert the string into structured objects.</li> <li>The <code>-ObjectPath</code> parameter is used with the output from <code>kubectl</code>. This is required because the output from <code>kubectl</code> is a collection of resources instead of individual resources. Specifically <code>-ObjectPath items</code> gets the resources from the <code>items</code> property of the output.</li> </ul> <pre><code># Validate resources from file\nInvoke-PSRule -InputPath resources.yaml;\n</code></pre> <pre><code># Validate resources directly from kubectl output\nkubectl get services -o yaml | Out-String | Invoke-PSRule -Format Yaml -ObjectPath items;\n</code></pre> <p>For this example, we limited the output to failed results with the following command:</p> <pre><code># Validate resources from file\nInvoke-PSRule -Path docs/scenarios/kubernetes-resources -InputPath docs/scenarios/kubernetes-resources/resources.yaml -Option docs/scenarios/kubernetes-resources/ps-rule.yaml -Outcome Fail;\n</code></pre> <p>The resulting output is:</p> <pre><code>   TargetName: app1-cache\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\ndeployment.HasMinimumReplicas       Fail       Deployments use a minimum of 2 replicas\ndeployment.NotLatestImage           Fail       Deployments use specific tags\ndeployment.ResourcesSet             Fail       Resource requirements are set for each container\n\n\n   TargetName: app1-cache-service\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nmetadata.Name                       Fail       Must have the app.kubernetes.io/name label\nmetadata.Version                    Fail       Must have the app.kubernetes.io/version label\nmetadata.Component                  Fail       Must have the app.kubernetes.io/component label\n\n\n   TargetName: app1-ui\n\nRuleName                            Outcome    Recommendation\n--------                            -------    --------------\nmetadata.Version                    Fail       Must have the app.kubernetes.io/version label\n</code></pre>"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#more-information","title":"More information","text":"<ul> <li>kubernetes.Rule.ps1 - Example rules for validating Kubernetes resources.</li> <li>resources.yaml - An example Kubernetes manifest.</li> <li>ps-rule.yaml - PSRule options configuration file.</li> </ul>"},{"location":"scenarios/validation-pipeline/validation-pipeline/","title":"Using within continuous integration","text":"<p>PSRule supports several features that make it easy to a continuous integration (CI) pipeline. When added to a pipeline, PSRule can validate files, template and objects dynamically.</p> <p>This scenario covers the following:</p> <ul> <li>Installing within a CI pipeline.</li> <li>Validating objects.</li> <li>Formatting output.</li> <li>Failing the pipeline.</li> <li>Generating NUnit output.</li> <li>Additional options.</li> </ul>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#installing-within-a-ci-pipeline","title":"Installing within a CI pipeline","text":"<p>Typically, PSRule is not pre-installed on CI worker nodes and must be installed. If your CI pipeline runs on a persistent virtual machine that you control, consider pre-installing PSRule. The following examples focus on installing PSRule dynamically during execution of the pipeline. Which is suitable for cloud-based CI worker nodes.</p> <p>To install PSRule within a CI pipeline execute the <code>Install-Module</code> PowerShell cmdlet.</p> <p>In the example below:</p> <ul> <li>When installing modules on Windows, modules will be installed into Program Files by default, which requires administrator permissions. Depending on your environment, the CI worker process may not have administrative permissions. Instead we can install PSRule for the current context running the CI pipeline by using the <code>-Scope CurrentUser</code> parameter.</li> <li>By default, this cmdlet will install the module from the PowerShell Gallery which is not trusted by default. Since a CI pipeline is not interactive, use the <code>-Force</code> switch to suppress the confirmation prompt.</li> </ul> <pre><code>Install-Module -Name PSRule -Scope CurrentUser -Force;\n</code></pre> <p>In some cases, installing NuGet and PowerShellGet may be required to connect to the PowerShell Gallery. The NuGet package provider can be installed using the <code>Install-PackageProvider</code> PowerShell cmdlet.</p> <pre><code>Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\nInstall-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n</code></pre> <p>The example below includes both steps together with checks:</p> <pre><code>if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n    Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction Ignore)) {\n    Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\n</code></pre> <pre><code>if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n    Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\n</code></pre> <p>See the change log for the latest version.</p>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validating-objects","title":"Validating objects","text":"<p>To validate objects use <code>Invoke-PSRule</code>, <code>Assert-PSRule</code> or <code>Test-PSRuleTarget</code>. In a CI pipeline, <code>Assert-PSRule</code> is recommended. <code>Assert-PSRule</code> outputs preformatted results ideal for use within a CI pipeline.</p> <p>For rules within the same source control repository, put rules in the <code>.ps-rule</code> directory. A directory <code>.ps-rule</code> in the repository root, is used by convention.</p> <p>In the following example, objects are validated against rules from the <code>./.ps-rule/</code> directory:</p> <pre><code>$items | Assert-PSRule -Path './.ps-rule/'\n</code></pre> <p>Example output:</p> <pre><code> -&gt; ObjectFromFile.psd1 : System.IO.FileInfo\n\n    [PASS] File.Header\n    [PASS] File.Encoding\n    [WARN] Target object 'ObjectFromFile.yaml' has not been processed because no matching rules were found.\n    [WARN] Target object 'ObjectFromNestedFile.yaml' has not been processed because no matching rules were found.\n    [WARN] Target object 'Baseline.Rule.yaml' has not been processed because no matching rules were found.\n\n -&gt; FromFile.Rule.ps1 : System.IO.FileInfo\n\n    [FAIL] File.Header\n    [PASS] File.Encoding\n</code></pre> <p>In the next example, objects from file are validated against pre-defined rules from a module:</p> <pre><code>Assert-PSRule -InputPath .\\resources-*.json -Module PSRule.Rules.Azure;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#formatting-output","title":"Formatting output","text":"<p>When executing a CI pipeline, feedback on any validation failures is important. The <code>Assert-PSRule</code> cmdlet provides easy to read formatted output instead of PowerShell objects.</p> <p>Additionally, <code>Assert-PSRule</code> supports styling formatted output for Azure Pipelines and GitHub Actions. Use the <code>-Style AzurePipelines</code> or <code>-Style GitHubActions</code> parameter to style output.</p> <p>For example:</p> <pre><code>$items | Assert-PSRule -Path './.ps-rule/' -Style AzurePipelines;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#failing-the-pipeline","title":"Failing the pipeline","text":"<p>When using PSRule within a CI pipeline, a failed rule should stop the pipeline. When using <code>Assert-PSRule</code> if any rules fail, an error will be generated.</p> <pre><code>Assert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path ./.ps-rule/\n+          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo          : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\n</code></pre> <p>A single PowerShell error is typically enough to stop a CI pipeline. If you are using a different configuration additionally <code>-ErrorAction Stop</code> can be used.</p> <p>For example:</p> <pre><code>$items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\n</code></pre> <p>Using <code>-ErrorAction Stop</code> will stop the current script and return an exit code of 1.</p> <p>To continue running the current script but return an exit code, use:</p> <pre><code>try {\n    $items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\n}\ncatch {\n    $Host.SetShouldExit(1);\n}\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#generating-nunit-output","title":"Generating NUnit output","text":"<p>NUnit is a popular unit test framework for .NET. NUnit generates a test report format that is widely interpreted by CI systems. While PSRule does not use NUnit directly, it support outputting validation results in the NUnit3 format. Using a common format allows integration with any system that supports the NUnit3 for publishing test results.</p> <p>To generate an NUnit report:</p> <ul> <li>Use the <code>-OutputFormat NUnit3</code> parameter.</li> <li>Use the <code>-OutputPath</code> parameter to specify the path of the report file to write.</li> </ul> <pre><code>$items | Assert-PSRule -Path './.ps-rule/' -OutputFormat NUnit3 -OutputPath reports/rule-report.xml;\n</code></pre> <p>The output path will be created if it does not exist.</p>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#publishing-nunit-report-with-azure-devops","title":"Publishing NUnit report with Azure DevOps","text":"<p>With Azure DevOps, an NUnit report can be published using Publish Test Results task.</p> <p>An example YAML snippet is included below:</p> <pre><code># PSRule results\n- task: PublishTestResults@2\n  displayName: 'Publish PSRule results'\n  inputs:\n    testRunTitle: 'PSRule'\n    testRunner: NUnit\n    testResultsFiles: 'reports/rule-report.xml'\n    mergeTestResults: true\n    publishRunAttachments: true\n  condition: succeededOrFailed()\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#complete-example","title":"Complete example","text":"<p>Putting each of these steps together.</p>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#install-dependencies","title":"Install dependencies","text":"<pre><code># Install dependencies for connecting to PowerShell Gallery\nif ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n    Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction SilentlyContinue)) {\n    Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validate-files","title":"Validate files","text":"<pre><code># Install PSRule module\nif ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n    Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\n\n# Validate files\n$assertParams = @{\n    Path = './.ps-rule/'\n    Style = 'AzurePipelines'\n    OutputFormat = 'NUnit3'\n    OutputPath = 'reports/rule-report.xml'\n}\n$items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n$items | Assert-PSRule $assertParams -ErrorAction Stop;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#azure-devops-pipeline","title":"Azure DevOps Pipeline","text":"<pre><code>steps:\n\n# Install dependencies\n- powershell: ./pipeline-deps.ps1\n  displayName: 'Install dependencies'\n\n# Validate templates\n- powershell: ./validate-files.ps1\n  displayName: 'Validate files'\n\n# Publish pipeline results\n- task: PublishTestResults@2\n  displayName: 'Publish PSRule results'\n  inputs:\n    testRunTitle: 'PSRule'\n    testRunner: NUnit\n    testResultsFiles: 'reports/rule-report.xml'\n    mergeTestResults: true\n    publishRunAttachments: true\n  condition: succeededOrFailed()\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#additional-options","title":"Additional options","text":""},{"location":"scenarios/validation-pipeline/validation-pipeline/#using-invoke-build","title":"Using Invoke-Build","text":"<p>Invoke-Build is a build automation cmdlet that can be installed from the PowerShell Gallery by installing the InvokeBuild module. Within Invoke-Build, each build process is broken into tasks.</p> <p>The following example shows an example of using PSRule with Invoke-Build tasks.</p> <pre><code># Synopsis: Install PSRule\ntask PSRule {\n    if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n        Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n    }\n}\n\n# Synopsis: Validate files\ntask ValidateFiles PSRule, {\n    $assertParams = @{\n        Path = './.ps-rule/'\n        Style = 'AzurePipelines'\n        OutputFormat = 'NUnit3'\n        OutputPath = 'reports/rule-report.xml'\n    }\n    $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n    $items | Assert-PSRule @assertParams -ErrorAction Stop;\n}\n\n# Synopsis: Run all build tasks\ntask Build ValidateFiles\n</code></pre> <pre><code>Invoke-Build Build;\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#calling-from-pester","title":"Calling from Pester","text":"<p>Pester is a unit test framework for PowerShell that can be installed from the PowerShell Gallery.</p> <p>Typically, Pester unit tests are built for a particular pipeline. PSRule can complement Pester unit tests by providing dynamic and sharable rules that are easy to reuse. By using <code>-If</code> or <code>-Type</code> pre-conditions, rules can dynamically provide validation for a range of use cases.</p> <p>When calling PSRule from Pester use <code>Invoke-PSRule</code> instead of <code>Assert-PSRule</code>. <code>Invoke-PSRule</code> returns validation result objects that can be tested by Pester <code>Should</code> conditions.</p> <p>Additionally, the <code>Logging.RuleFail</code> option can be included to generate an error message for each failing rule.</p> <p>For example:</p> <pre><code>Describe 'Azure' {\n    Context 'Resource templates' {\n        It 'Use content rules' {\n            $invokeParams = @{\n                Path = './.ps-rule/'\n                OutputFormat = 'NUnit3'\n                OutputPath = 'reports/rule-report.xml'\n            }\n            $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n            Invoke-PSRule @invokeParams -Outcome Fail,Error | Should -BeNullOrEmpty;\n        }\n    }\n}\n</code></pre>"},{"location":"scenarios/validation-pipeline/validation-pipeline/#more-information","title":"More information","text":"<ul> <li>pipeline-deps.ps1 - Example script installing pipeline dependencies.</li> <li>file.Rule.ps1 - Example rules for validating script files.</li> <li>validate-files.ps1 - Example script for running files validation.</li> <li>azure-pipelines.yaml - An example Azure DevOps Pipeline.</li> </ul>"},{"location":"specs/design-spec/","title":"PSRule design specification (draft)","text":"<p>This document is intended as a working technical specification for PSRule.</p>"},{"location":"specs/design-spec/#what-is-psrule","title":"What is PSRule?","text":"<p>PSRule is an engine, shipped as a PowerShell module designed to validate infrastructure as code (IaC). Additionally, PSRule can validate any PowerShell object, allowing almost any custom scenario to be supported.</p> <p>PSRule natively supports common infrastructure code artifacts with the following file formats:</p> <ul> <li>YAML (<code>.yaml</code> or <code>.yml</code>).</li> <li>JSON (<code>.json</code>).</li> <li>PowerShell Data Files (<code>.psd1</code>).</li> <li>Markdown front matter (<code>.md</code> or <code>.markdown</code>).</li> </ul> <p>While some infrastructure as code languages implement their own custom language, many support output into a standard artifact format. i.e. <code>terraform show -json</code></p>"},{"location":"specs/design-spec/#project-objectives","title":"Project objectives","text":"<ol> <li>Extensible:<ul> <li>Provide an execution environment (tools and language) to validate infrastructure code.</li> <li>Handling of common concerns such as input/ output/ reporting should be handled by the engine.</li> <li>Language must be flexible enough to support a wide range of use cases.</li> </ul> </li> <li>DevOps:<ul> <li>Validation should support and enhance DevOps workflows by providing fast feedback in pull requests.</li> <li>Allow quality gates to be implemented between environments such development, test, and production.</li> </ul> </li> <li>Cross-platform:<ul> <li>A wide range of platforms can be used to author and deploy infrastructure code. PSRule must support rule validation and authoring on Linux, MacOS, and Windows.</li> <li>Runs in a Linux container. For continuous integration (CI) systems that do not support PowerShell, run in a container.</li> </ul> </li> <li>Reusable:<ul> <li>Validation should plug and play, reusable across teams and organizations.</li> <li>Any reusable validation will have exceptions. Rules must be able to be disabled where they are not applicable.</li> </ul> </li> </ol>"},{"location":"specs/design-spec/#language-specification","title":"Language specification","text":"<p>PSRule is rooted in PowerShell. This provides significant benefits and flexibility including:</p> <ul> <li>Reuses existing skills within Microsoft and customers who already know how to author PowerShell scripts.</li> <li>Builds on existing PowerShell community; allowing existing integrations and cmdlets to be used.</li> <li>PowerShell already has an established model for distributing packages (modules). This includes options for trust and hosting (publicly or privately).</li> </ul> <p>To ensure these benefits remain, the following must be true:</p> <ul> <li>Rules can be written using standard PowerShell operators and conventions. Minimal knowledge of PSRule should be required to author rules.</li> <li>Rules validate an object graph. Whether an object originates from a YAML or JSON file should be abstract.</li> </ul>"},{"location":"specs/design-spec/#future-cases","title":"Future cases","text":"<p>PowerShell offers complete flexibility to build simple to complex rules. However, rule authors may be unfamiliar with PowerShell. Authoring rules in YAML or JSON with a defined schema will allow additional options for basic rules.</p>"},{"location":"specs/design-spec/#concepts","title":"Concepts","text":""},{"location":"specs/design-spec/#rule-definitions","title":"Rule definitions","text":"<p>Rule definitions or rules are defined using PowerShell. Rules can be created in a PowerShell script file with the <code>.Rule.ps1</code> extension. Rule files can be created and used individually or bundled as a module.</p> <p>Each rule:</p> <ul> <li>Implements a test for one or more conditions against an object. When all conditions return true the rule passes, if not the rule fails.</li> <li>Is evaluated by executing the rule within a sandbox that provides context to each rule. Such as the deserialized object being processed and configuration.</li> <li>Can specify preconditions which determine if a rule should be evaluated based on the object being processed. Rules only run against the objects they are designed to test.</li> </ul> <p>For example:</p> <pre><code>Rule 'NameOfRule' {\n    # &lt;Rule conditions&gt;\n}\n</code></pre> <pre><code># Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'StorageAccounts.UseHttps' -Type 'Microsoft.Storage/storageAccounts' {\n    $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\n</code></pre>"},{"location":"specs/design-spec/#psrule-engine","title":"PSRule engine","text":"<p>Distributed as a PowerShell module, all source code is included within this repository. This included cmdlets and an execution sandbox where rules are evaluated. PSRule is designed to be self contained, requiring only PowerShell to run.</p> <p>By itself PSRule doesn't implement any specific rules. Custom rules can be defined and evaluated from PowerShell script files. Reusable rules can be distributed using PowerShell modules. Use PowerShellGet to install modules from public and private sources.</p> <p>PSRule extends PowerShell with domain specific language (DSL) keywords, cmdlets, and automatic variables. These language features are only available within the sandbox. Stubs are exported from PSRule module to provide command completion during authoring.</p> <p>In additional to rules, a number of resources can be used within PSRule. Resources are defined in YAML files with the <code>.Rule.yaml</code> file extension. You can create one or many resource within a single <code>.Rule.yaml</code> file.</p> <p>PSRule supports the following resources:</p> <ul> <li><code>Baseline</code> - A reusable group of rules and configuration defaults for a given scenario.</li> <li><code>Selector</code> - A reusable filter to determine which objects a rule should be run against.</li> </ul> <p>A special <code>ModuleConfig</code> resource can also be defined to configure defaults for a module.</p>"},{"location":"specs/design-spec/#keywords-and-variables","title":"Keywords and variables","text":"<p>TBA</p>"},{"location":"specs/design-spec/#baselines","title":"Baselines","text":"<p>A baseline is a resource defined in YAML that determines which rules to run for a given scenario. One or more baselines can be included in a <code>.Rule.yaml</code> file. Baselines can be created individually or bundled in a module.</p> <p>Common use cases where baselines are helpful include:</p> <ul> <li>Separation of rules or features in development. For infrastructure code or rules early in their lifecycle, a recommend practice may not be fully ratified. Baselines allow rules to be distributed but not executed by default.</li> <li>Progressive adoption. If validation has been added for a new use case, it may not be possible to adopt all rules at once. Baselines act as checkpoints to allow validation of a subset of rules.</li> </ul>"},{"location":"specs/design-spec/#execution","title":"Execution","text":"<p>Execution within PSRule occurs within a pipeline. The PSRule pipeline is similar to PowerShell and contains a <code>begin</code>, <code>process</code>, and <code>end</code> stage.</p> <ul> <li>Begin: TBA</li> <li>Process: TBA</li> <li>End: TBA</li> </ul> <p>Three execution pipelines exist, <code>Invoke</code>, <code>Assert</code>, or <code>Test</code>. Differences between each of these pipeline is minimal and mostly deals with how output is presented.</p> <ul> <li>Invoke: Returns output as pipeline objects so they can be natively processed by PowerShell code.</li> <li>Assert: Returns output as styled text to provide readable results within a CI pipeline.</li> <li>Test: Returns true or false based on pass or fail of each object. Use this option to use filter objects from a PowerShell pipeline.</li> </ul>"},{"location":"specs/design-spec/#execution-sandbox","title":"Execution sandbox","text":"<p>The execution sandbox is implemented using PowerShell runspaces. Runspaces are a PowerShell feature which enable partial isolation within a PowerShell process.</p> <p>PSRule uses two discrete runspaces:</p> <ul> <li>In the parent runspace where PSRule is called using <code>Invoke-PSRule</code>, <code>Assert-PSRule</code>, or <code>Test-PSRule</code>. The parent runspace is responsible for all input and output.</li> <li>The sandbox runspace is where rules execute. PSRule keywords and automatic variables are implemented in the sandbox. Flow control within the PSRule pipeline maintains context for each object as it is processed by rules.</li> </ul> <p>Input and output are proxied between the two discrete runspaces to maintain runspace separation. This separation allows rules to be executed without polluting the state of the parent runspace.</p>"},{"location":"specs/design-spec/#rule-evaluation","title":"Rule evaluation","text":"<p>TBA</p>"},{"location":"specs/design-spec/#configuration","title":"Configuration","text":"<p>PSRule has built-in support for configuration of the engine and rules. Configuration can be set by:</p> <ul> <li>Configuring the default <code>ps-rule.yaml</code> file.</li> <li>Setting at runtime by passing a <code>-Option</code> parameter to PSRule cmdlets.</li> </ul>"},{"location":"specs/design-spec/#engine-options","title":"Engine options","text":"<p>Configuration of the PSRule engine is referred to as options. Each option changes the default that PSRule uses during execution. The supported options that can be configured for PSRule are described in the about_PSRule_Options topic.</p>"},{"location":"specs/design-spec/#rule-configuration","title":"Rule configuration","text":"<p>Separately, rules can optionally define configuration that can skip or change the rule conditions. Rule configuration is a key/ value pair.</p>"},{"location":"specs/design-spec/#integration","title":"Integration","text":"<p>TBA</p>"},{"location":"specs/function-spec/","title":"PSRule function expressions spec (draft)","text":"<p>This is a spec for implementing function expressions in PSRule v2.</p>"},{"location":"specs/function-spec/#synopsis","title":"Synopsis","text":"<p>Functions are available to handle complex conditions within YAML and JSON expressions.</p>"},{"location":"specs/function-spec/#schema-driven","title":"Schema driven","text":"<p>While functions allow handing for complex use cases, they should still remain schema driven. A schema driven design allows auto-completion and validation during authoring in a broad set of tools.</p>"},{"location":"specs/function-spec/#syntax","title":"Syntax","text":"<p>Functions can be used within YAML and JSON expressions by using the <code>$</code> object property. For example:</p> <pre><code>---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n  name: Yaml.Fn.Example1\nspec:\n  if:\n    value:\n      $:\n        substring:\n          path: name\n        length: 3\n    equals: abc\n</code></pre>"},{"location":"specs/option-spec/","title":"PSRule options spec (draft)","text":"<p>This is a spec for implementing options in PSRule v2.</p>"},{"location":"specs/option-spec/#synopsis","title":"Synopsis","text":"<p>When executing resources options is often required to control the specific behaviour. In additional, many of these cases are scoped to the module being used.</p> <p>The following scopes exist:</p> <ul> <li>Parameter</li> <li>Local options</li> <li>Baseline</li> <li>Module configuration</li> </ul>"}]}
\ No newline at end of file