en-GB/about_PSRule_Badges.help.txt

TOPIC
    about_psrule_badges
 
SHORT DESCRIPTION
    Describes using the badge API with PSRule.
 
LONG DESCRIPTION
    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.
 
    USING THE API
    PSRule provides the `$PSRule` built-in variable that exposes the badge API.
    By using the `$PSRule.Badges.Create` method you can create a standard or
    custom badge.
    The create method provides the following overloads:
 
    // Create a badge for the worst case of an analyzed object.
    IBadge Create(InvokeResult result);
     
    // Create a badge for the worst case of all analyzed objects.
    IBadge Create(IEnumerable<InvokeResult> result);
     
    // Create a custom badge.
    IBadge Create(string title, BadgeType type, string label);
 
    A badge once created can be read as a string or written to disk with the
    following methods:
 
    // Get the badge as SVG text content.
    string ToSvg();
     
    // Write the SVG badge content directly to disk.
    void ToFile(string path);
 
    DEFINING CONVENTIONS
    To define a convention, add a `Export-PSRuleConvention` block within a
    `.Rule.ps1` file. The `.Rule.ps1` must be in an included path or module with
    `-Path` or `-Module`.
    The `Export-PSRuleConvention` block works similar to the `Rule` block. Each
    convention must have a unique name. Currently the badge API support creating
    badges in the `-End` block.
    For example:
 
    # Synopsis: A convention that generates a badge for an aggregate result.
    Export-PSRuleConvention 'Local.Aggregate' -End {
        $PSRule.Badges.Create($PSRule.Output).ToFile('out/badges/aggregate.svg');
    }
 
    # Synopsis: A convention that generates a custom badge.
    Export-PSRuleConvention 'Local.CustomBadge' -End {
        $PSRule.Badges.Create('PSRule', [PSRule.Badges.BadgeType]::Success, 'OK').ToFile('out/badges/custom.svg');
    }
 
    USING CONVENTIONS
    A convention can be included by using the `-Convention` 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:
 
    Invoke-PSRule -Convention 'Local.Aggregate';
 
NOTE
    An online version of this document is available at
    https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Badges/.
 
SEE ALSO
    -
    Invoke-PSRule
 
KEYWORDS
    - Badges
- Conventions
- PSRule