Project Structure

The SmartAceDesigns.ScriptoFormTemplates PowerShell module includes the New-SADScriptoFormProject function which is used to build a new ScriptoForm project. This function will generate a default set of files. These files are all you need to run your ScriptoForm and optionally compile it into an executable format. In addition to these default files, you may also want to add optional support files to the project directory that your ScriptoForm can make use of when running.

The following section describes how a ScriptoForm project is organized and the initial set of files you will find in your new ScriptoForm project directory.

Directories and Files

A ScriptoForm project structure is opinionated and requires some files to be present and have a specific name and location in the project directory. Other files are optional or are named based on parameters you provided when the ScriptoForm was generated. Every new ScriptoForm project will include the following files by default:

• “Build/Build.cs” - a C# source file that is compiled into a excutable and used to launch your ScriptoForm PowerShell script. Compiling the script into an excutable is optional and not required to use a ScriptoForm.
• “Build/Build.csproj” - a C# project file used to define the instructions for compiling your ScriptoForm PowerShell script and optional support files into an executable.
• “.gitignore” - a standard Git ingore file for the project
• “README.md” - a stardard README markdown file for the project.
• “ScriptName.ps1” - the ScriptoForm PowerShell script source file.

Tip

As best practice, you should name your ScriptoForm project using the standard Verb-Noun format.

Initial Project Structure

• DirectoryBuild

  • Build.cs
  • Build.csproj
• .gitignore
• README.md
• ScriptName.ps1

Build/

The “Build” directory contains the C# files used for compiling the ScriptoForm into a executable. This includes:

• Build.cs
• Build.csproj

Caution

These file names should not be changed. However, the files and “Build” folder can be removed if you do not plan to compile your ScriptoForm.

”Build.cs” is the C# source file used to compile your ScriptoForm PowerShell script into an executable format. Normally the Build.cs file is static and should never be modified.

”Build.csproj” is the .NET project file that provides the settings to use when compiling “Build.cs” into an executable. This file is modified initially by the New-SADScriptoFormProject function to set various properties unique to your project such as the PowerShell script name and the executable name. It does so with the help of the PowerShell Plaster module which provides powerful variable substitution (e.g. $PLASTER_PARAM_Name). You may also need to modify this file yourself if you need to reference additional support files in the project that need to be embedded as resource files in the executable.

Build.csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <AssemblyName><%= $PLASTER_PARAM_Name %></AssemblyName>
    <ApplicationIcon></ApplicationIcon>
    <OutputType>WinExe</OutputType>
    <GenerateAssemblyFileVersionAttribute>false</GenerateAssemblyFileVersionAttribute>
    <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
    <GenerateAssemblyTitleAttribute>false</GenerateAssemblyTitleAttribute>
    <TargetFrameworks>net48;net8.0-windows;net9.0-windows;net10.0-windows</TargetFrameworks>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <DebugType>None</DebugType>
    <Configuration>Release</Configuration>
    <SelfContained>false</SelfContained>
    <PublishSingleFile Condition="'$(TargetFramework)' != 'net48'">true</PublishSingleFile>
  </PropertyGroup>

  <ItemGroup>
    <EmbeddedResource Include="..\<%= $PLASTER_PARAM_Name %>.ps1">
        <LogicalName>Script.ps1</LogicalName>
    </EmbeddedResource>
  </ItemGroup>

  <Target Name="Cleanup" AfterTargets="Clean">
    <RemoveDir Directories="$(BaseIntermediateOutputPath)"/>
    <RemoveDir Directories="$(BaseOutputPath)"/>
  </Target>

</Project>

.gitignore

This is a standard Git ignore file that instructs Git to ignore the following directories, which are used when compiling the PowerShell script into an executable and should not be tracked by Git:

• bin/
• obj/
• Release/

This file can be removed from your project if you do not plan to use source control.

README.md

This is a standard README file for use with your source control, such as Git. It provides opinionated default content which can be edited as you see fit for your project. This file can be removed from your project if you do not plan to use source control.

ScriptName.ps1

This is the PowerShell script that contains all the code used by your ScriptoForm. The name of this file is set to be same as the name of project you provided when using the New-SADScriptoFormProject function. For example, if the name of your project is New-ADCustomUser then the script file will be named “New-ADCustomUser.ps1” when the project files are generated. This file can be renamed later, but should not be removed for obvious reasons. If you decide to rename the file, you should also update the “Build.csproj” to reflect the new name if you plan to compile the ScriptoForm into an executable. It is also recommended to change the project directory name to match the new script name.