PSModuleDevelopment

The PSFramework provides a configuration system designed to manage settings with high levels of automation and control. Using this system allows you to:

• Publish settings: Make settings available to the user.
• Onboard documentation: Include documentation alongside settings.
• Input validation: Ensure settings meet specific criteria before being applied.
• Reactive scripts: Execute specific scripts automatically when settings change.
• User discovery: Allow users to discover and update settings easily.
• Policy administration: Manage settings via Group Policy or Desired State Configuration (DSC).

For detailed implementation guidance and complex configuration scenarios, visit the official documentation at http://psframework.org.

The PSFTests directory is organized into two distinct testing categories to ensure module quality:

1. General Tests: These are function-generic tests that perform a general module health check. They verify adherence to style guides, check for syntax errors, enforce command usage policies, ensure best practices, and validate that commands have proper help documentation.
2. Function Tests: These are specific unit and integration tests for the individual commands and components shipped within the module. Unlike general tests, these are not templated because they must be tailored to the specific logic of each function.

The Azure Function template project is organized into three primary directories:

• build/: Contains the build logic and configuration. Do not modify files here except for build.config.psd1.
• function/: Contains the base Function App files. You may update requirements.psd1 for Managed Dependencies (note: Managed Dependencies are not supported on the Flex Consumption plan).
• <name>/: The root folder for your specific project. This contains the PowerShell module that is transformed into the function app. This is where most development occurs.

The bin folder is used to store binary data and scripts related to the module's type system. You can use this directory to include:

• Your own C#-based libraries.
• Third-party libraries (ensure you comply with their licenses).
• Scripts that declare Type Accelerators (which act as aliases for .NET types).

For managing type accelerators, refer to the Set-PSFTypeAlias documentation.

Tab Expansion Plus Plus (TEPP) allows you to define specific options offered to a user when they use the TAB key to cycle through input options. This improves user experience by providing context-aware completions.

To implement custom tab completion, follow these two steps:

1. Define the completion logic: Create a scriptblock that executes when the user hits TAB. This scriptblock must return the list of strings that serve as the available options.
2. Assign the completion logic: Assign that scriptblock to the specific parameter of a command. You can reuse the same scriptblock for multiple parameters.

To minimize the impact on import times, each project should contain exactly one format file and one type extension file. Use the following naming pattern (replacing þnameþ with your project name):

• Format XML: þnameþ.Format.ps1xml
• Type Extension XML: þnameþ.Types.ps1xml

Project XML files should be stored in the xml folder. This folder is specifically for:

• Format XML: Defines how objects are displayed in the console.
• Type Extension XML: Defines how types are serialized/deserialized.

Important: Do not place external help files in this folder.

To build a complete AppLocker configuration, use the following directory structures:

• Apps: Use this directory to describe each application. The goal is to ensure AppLocker is aware of all required binaries for that specific app. Refer to the Git sample in the template for the expected structure.
• Domains: Use this directory to describe content that is relevant to specific organizational domains.
• Generics: Use this for baseline settings. It is currently recommended to only use a Windows generic configuration (e.g., to disable PowerShell 2 globally).

The internal/scripts directory is used to host files that execute automatically when the PowerShell module is imported. Unlike standard module files that primarily export functions, these scripts allow you to perform side effects or setup tasks during the module's lifecycle.

Common use cases for internal scripts include:

• Connecting to an external service.
• Loading configuration data into the session.
• Defining tab completion logic.

The configurationdata directory uses a hierarchical merging strategy defined by ResolutionPrecedence in Datum.yml. Settings are merged in a specific order where later items in the precedence list override or augment earlier ones.

In this template, the precedence is:

1. Generics\Windows: Base Windows settings applied first.
2. Domains$($Node.Domain): Domain-specific settings merged next.
3. Apps$_: App-specific configurations merged after domains.
4. AllNodes$($Node.PolicyName): The specific policy settings applied last.

This allows you to define a global baseline (Generics), refine it by domain, add application-specific requirements, and finally apply unique policy-level overrides.

ResolutionPrecedence:
  - AllNodes\$($Node.PolicyName)
  - '[x= { $Node.Apps | Foreach-Object {"Apps\$_"} } =]'
  - Domains\$($Node.Domain)
  - Generics\Windows

Tab Expansion Plus Plus (TEPP) allows you to define custom options that users are offered when tabbing through input parameters in a command. This improves user experience by providing relevant, context-aware suggestions.

To implement custom tab completion, follow these two steps:

1. Define the completion logic: Create a scriptblock that executes when the user hits TAB. This scriptblock must return the list of strings that should be presented as options.
2. Assign the completion logic: Assign that scriptblock to the specific parameter of a command. You can reuse the same scriptblock for multiple parameters.