Levitate.Runtime 1.0.1

Levitate

Compile C# automation methods into production-grade PowerShell at build time.

Levitate is a Roslyn source generator and automation toolkit for teams that want C# ergonomics with PowerShell output they can inspect, validate, save, execute, and ship. Mark a static C# method with [PowerShellScript]; Levitate translates the supported method body into PowerShell during compilation and generates a strongly named C# accessor for the script.

It is built for infrastructure automation, internal ops tools, admin portals, LLM-assisted runbooks, and deployment workflows where string-built scripts are too fragile.

What Levitate Gives You

Install

For compile-time generation:

<ItemGroup>
  <PackageReference Include="Levitate.Attributes" Version="1.0.1" />
  <PackageReference Include="Levitate.Runtime" Version="1.0.1" />
  <PackageReference Include="Levitate.Generator" Version="1.0.1"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false"
                    PrivateAssets="all" />
  <PackageReference Include="Levitate.Build" Version="1.0.1" PrivateAssets="all" />
</ItemGroup>

For fluent script building without the source generator:

dotnet add package Levitate.Core --version 1.0.1
dotnet add package Levitate.Runtime --version 1.0.1

For starter projects:

dotnet new install Levitate.Templates::1.0.1
dotnet new levitate-console
dotnet new levitate-ops-tool

First Script

using Levitate;
using System;
using System.IO;

namespace Company.Automation;

public partial class MaintenanceScripts
{
    [PowerShellScript]
    public static void CleanTempFiles(string tempPath, int olderThanDays)
    {
        if (!Directory.Exists(tempPath))
        {
            Console.Error.WriteLine($"Missing path: {tempPath}");
            return;
        }

        Console.WriteLine($"Cleaning {tempPath}");
        PS.Raw("Get-ChildItem -Path $tempPath -File | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-$olderThanDays) } | Remove-Item -Force");
    }
}

Levitate generates a PowerShell script and a C# accessor:

var script = MaintenanceScripts.CleanTempFilesScript.PowerShell;

await MaintenanceScripts.CleanTempFilesScript.ExecuteAsync(
    tempPath: @"C:\Temp",
    olderThanDays: 14);

MaintenanceScripts.CleanTempFilesScript.SaveTo("clean-temp.ps1");

Generated PowerShell is ordinary, reviewable text:

param(
    [Parameter(Mandatory=$true)]
    [string]$tempPath,
    [Parameter(Mandatory=$true)]
    [int]$olderThanDays
)

if (-not (Test-Path $tempPath -PathType Container)) {
    Write-Error "Missing path: $tempPath"
    return
}

Write-Host "Cleaning $tempPath"
Get-ChildItem -Path $tempPath -File | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-$olderThanDays) } | Remove-Item -Force

Package Map

Supported C# Translation

Levitate intentionally supports a clear automation profile instead of trying to become a full C# runtime inside PowerShell.

BCL To PowerShell Mappings

Levitate maps common .NET automation calls to idiomatic PowerShell:

See docs/bcl-mappings.md for the detailed table.

Pipelines And LINQ Preview

Use PS.Command(...) when the intent is a PowerShell object pipeline:

[PowerShellScript]
public static void RunningServices()
{
    PS.Command("Get-Service")
        .Where("Status", PsOperator.Eq, "Running")
        .Select("Name", "Status")
        .SortBy("Name")
        .FormatTable();
}

Generated pipeline:

Get-Service | Where-Object { $_.Status -eq "Running" } | Select-Object Name, Status | Sort-Object Name | Format-Table -AutoSize

Supported pipeline stages include:

The LINQ preview translates common object-pipeline forms including Where, Select, Any, All, Count, First, FirstOrDefault, Last, LastOrDefault, OrderBy, ThenBy, descending variants, GroupBy, Skip, Take, Distinct, ToList, and ToArray.

Module-Aware Ops APIs

Levitate includes marker APIs that compile to module-specific PowerShell commands. They are compile-time markers and intentionally throw if executed directly as normal C#.

Example:

using Levitate;

public partial class CloudScripts
{
    [RequiresPowerShell("7.4")]
    [RequiresModule("Az")]
    [PowerShellScript]
    public static void StopDevVm(string name, string resourceGroup)
    {
        Azure.StopVM(name, resourceGroup);
    }
}

Generated prefix and command:

#Requires -Version 7.4
#Requires -Modules Az

param(
    [Parameter(Mandatory=$true)]
    [string]$name,
    [Parameter(Mandatory=$true)]
    [string]$resourceGroup
)

Stop-AzVM -Name $name -ResourceGroupName $resourceGroup -Force

Manifest, Platform, And Safety Features

Generated Artifacts

Levitate can emit scripts as build artifacts so reviewers and CI can inspect the exact PowerShell that will run.

<PropertyGroup>
  <LevitateEmitPs1>true</LevitateEmitPs1>
  <LevitatePs1OutputPath>Scripts/Generated</LevitatePs1OutputPath>
  <LevitateValidateGeneratedScripts>true</LevitateValidateGeneratedScripts>
  <LevitateStrictMode>true</LevitateStrictMode>
  <LevitateErrorActionPreference>Stop</LevitateErrorActionPreference>
</PropertyGroup>

Default generated location:

obj/Levitate/generated/

Accessor helpers generated for every script method:

Diagnostics

Levitate diagnostics are designed to be actionable. v1.0 messages include rewrite suggestions for the most common blockers.

LLM-Safe Automation Workflow

Levitate works well as a compiler layer between AI-generated C# and executable PowerShell:

1. Ask an LLM for Levitate-profile C# instead of raw shell commands.
2. Build the project so normal C# compilation, analyzers, and Levitate diagnostics run.
3. Inspect generated .ps1 artifacts.
4. Parse-validate generated PowerShell in tests.
5. Execute through Levitate.Runtime only after review.

The recommended LLM profile is documented in docs/llm-guide.md.

Runtime Execution

var result = await MaintenanceScripts.CleanTempFilesScript.ExecuteAsync(
    tempPath: @"C:\Temp",
    olderThanDays: 14);

if (!result.Success)
{
    Console.Error.WriteLine(result.ErrorOutput);
}

foreach (var line in result.AsLines())
{
    Console.WriteLine(line);
}

ExecutionResult includes:

Fluent Builder

When you want to generate PowerShell without source generation, use Levitate.Core directly:

using Levitate.Core;
using Levitate.Core.Conditions;

var ps = Shell.New()
    .Echo("Levitate works")
    .If(new FileExistsCondition("$profile"), thenBlock => thenBlock
        .Raw("Write-Host \"Profile exists\""))
    .Build();

The builder layer includes AST nodes for commands, pipelines, functions, script blocks, variables, conditionals, loops, switch statements, try/catch blocks, here-strings, JSON/XML operations, jobs, sessions, scheduled tasks, certificates, services, registry, networking, storage, and more.

Cross-Platform Guidance

Levitate targets PowerShell 7 where possible and can fall back to Windows PowerShell on Windows through the runtime. Cross-platform scripts should prefer file/path/process/environment APIs, portable pwsh cmdlets, and explicit module requirements.

Windows-specific automation is supported, but should be marked clearly:

[RequiresModule("WebAdministration")]
[TargetPlatform(PowerShellPlatform.Windows)]
[PowerShellScript]
public static void RestartSite(string siteName)
{
    IIS.RestartSite(siteName);
}

Build And Test

dotnet restore Levitate.slnx
dotnet build Levitate.slnx --configuration Release
dotnet test Levitate.slnx --configuration Release --no-build
dotnet pack Levitate.slnx --configuration Release --no-build --output nupkgs/Levitate/v1.0.1

The v1.0 tree validates generator output with golden tests and PowerShell parser checks.

Documentation

• Getting started
• How it works
• API reference
• Supported constructs
• BCL mappings
• Raw PowerShell guide
• Cross-platform guide
• Library guide
• LLM guide

Release

Levitate v1.0.1 is the Trustworthy Automation Compiler release:

• Stable public package identities under Levitate.*.
• Compile-time source generation with reviewable PowerShell artifacts.
• Runtime execution support for generated scripts.
• BCL, pipeline, LINQ preview, IIS, AD, Azure, registry, service, and certificate mappings.
• Strict mode, manifest attributes, platform diagnostics, and raw PowerShell injection-risk warnings.