Export-RjRbXlsx

Azure Automation runbooks からオブジェクトを、外部モジュールの依存関係なしに、スタイル付きのネイティブ Excel ワークブック (.xlsx) にエクスポートします。

概要

Export-RjRbXlsx は、RealmJoin のレポート実行ブックから Excel レポート ファイル（.xlsx）を生成するための標準ヘルパーです。 PSCustomObjectの 1 つ以上のテーブルを ネイティブな Excel ブック として書き出します。使用するのは .NET のみ（System.IO.Compression）で、 ImportExcel は不要です。COM オートメーションも不要で、Automation 環境では他の外部モジュールも必要ありません。

まだ RealmJoin.RunbookHelper の一部ではありません。 Export-RjRbXlsx はまだ RealmJoin.RunbookHelper モジュールに同梱されておらず、 次のモジュール リリースで含まれる予定です。それまでは、この関数は使用している runbook 内にインラインで複製されており、たとえば次のファイルからコピーできます。 sync-MFA-secure-users-to-group_scheduled.ps1 （region 関数定義).

主な特徴:

• モジュール依存関係ゼロ — ブックは System.IO.Compression.ZipArchiveを使って Open XML パッケージとして直接組み立てられます。これにより、重いモジュールのコールド スタート コストと、混在したレポート用 runbook におけるアセンブリ競合の両方を回避できます。
• スタイル付きで、そのまま共有できる出力 — 各ワークシートには、スタイル付きの Excel テーブル（紺色のヘッダー、再並べ替えに追従するゼブラ行、フィルター ドロップダウン）、固定ヘッダー行、計算された列幅、そして自動印刷設定（用紙方向は内容の幅から決定、ヘッダー行は各印刷ページで繰り返し）が付きます。最初のワークシート タブは RealmJoin オレンジで色付けされます。
• 型を忠実に反映したセル — .NET の数値は Excel の数値になり、 日時 値および ISO-8601 文字列（例: Graph の日付フィールド）は、実際に並べ替え可能な Excel 日付になり（クライアント側でローカライズ）、 http/https URL はクリック可能なハイパーリンクになります。その他の文字列はすべてテキストのままです。シリアル番号や IMEI のような値が数値に変換されることはなく、 数式インジェクションは起こりません.
• 1 シートまたは複数シート — 行を 1 枚のシートに流し込むか、順序付きディクショナリを渡して、複数のワークシートと任意の「Info」カバー シートを持つブックを作成します。
• 組み込みのレポート仕上げ — 状態列向けの条件付き書式のハイライト ルール、数値列向けのセル内データ バー、見やすいハイパーリンク表示テキスト、桁区切りを任意で利用できます。

典型的な利用者は、CSV と XLSX ファイルを生成し、その後 Send-RjRbReportEmail および/または Publish-RjRbFilesToStorageContainer.

前提条件

PowerShell 自体以外にはありません。関数は、すべての Azure Automation ランタイムで利用可能な .NET 型のみを使用します（System.IO.Compression, System.Text, System.Xmlを使わない文字列生成）。Graph や Az への接続は不要です。関数はローカル データだけで動作し、ローカル ファイルを書き込みます。

クイック スタート

最小限の呼び出しでは、行を関数にパイプし、出力パスを指定します。

$devices | Export-RjRbXlsx -Path (Join-Path $env:TEMP 'devices.xlsx') -WorksheetName 'Devices'

これにより、1 つの「Devices」ワークシートを持つブックが生成されます。フィルター ドロップダウン付きのスタイル付きテーブル、固定ヘッダー行、自動サイズ調整された列、印刷設定があり、レポート メールへの添付やストレージ コンテナーへのアップロードにそのまま使えます。

パラメーター

パラメーター セット

この関数には 2 つのパラメーター セットがあります。

パラメーター セット	入力	用途
SingleSheet （既定）	-InputObject （パイプライン経由でも可） + -WorksheetName	1 つのテーブル、1 つのワークシート。
MultiSheet	-Worksheets （順序付きディクショナリ）	複数のテーブルを 1 つのブック内の別々のワークシートとして配置します。

必須

パラメーター	種類	説明
Path	string	作成する .xlsx ファイルのフル パス。 既存のファイルは上書きされます。

データ入力

パラメーター	種類	パラメーター セット	説明
InputObject	object[]	SingleSheet	書き出す行（オブジェクト配列。パイプライン経由でも受け付けます）。列の順序は最初のオブジェクトのプロパティ順に従います。ディクショナリ/ハッシュテーブルはオブジェクトに変換されます。
WorksheetName	string	SingleSheet	単一ワークシートの名前。既定値: Report.
Worksheets	IDictionary	MultiSheet	ワークシート名 → 行 の順序付きディクショナリ。例: ([ordered]@{ 'Summary' = $summary; 'Details' = $details })。少なくとも 1 つのエントリが必要です。

任意 — 内容と書式

パラメーター	種類	既定値	説明
CoverSheet	IDictionary	—	順序付きディクショナリを「Info」カバー ワークシート（最初のタブ）としてレンダリングします。 Title キーが見出しになり、その他のキーはすべてラベル/値の行になります。例: ([ordered]@{ Title = 'Device Report'; Tenant = 'contoso'; Generated = '2026-07-16 08:00 UTC' }).
HighlightRules	object[]	—	状態列に対する条件付き書式。以下を持つハッシュテーブル配列です。 Column （ヘッダー名）、 値 （完全一致のセル テキスト、大小文字を区別しない）、および Color (Green, Red または Yellow — Excel の定番ハイライト プリセット）。ルールは、指定した列を含むすべてのワークシートに適用されます。
DataBarColumns	object[]	—	セル内データ バー（オレンジ、最小値から最大値へのグラデーション）が付く数値列名。例: @('DeviceCount')。ワークシート上に存在しない列はスキップされます。
HyperlinkText	IDictionary	—	ハイパーリンク セルの列名 → 表示テキスト。例: @{ Portal = 'Open in Intune' }。セルには親しみやすいテキストが表示され、リンク先は完全な URL のままです。マッピングのない列は URL の表示を維持します。
NoHyperlink	スイッチ	無効	変換しない http/https URL 文字列をクリック可能なハイパーリンクに。
HideGridLines	スイッチ	無効	テーブル外のワークシートのグリッド線を非表示にします（既定では見やすさのためグリッド線は保持され、カバー シートは常に非表示です）。
UseThousandsSeparator	スイッチ	無効	数値セルを桁区切りで書式設定します（#,##0 整数の場合は #,##0.00 、小数の場合は（Excel によりローカライズされます）。

使用例

複数ワークシート

Export-RjRbXlsx `
    -Worksheets ([ordered]@{ 'Summary' = $summaryRows; 'Details' = $detailRows }) `
    -Path (Join-Path $env:TEMP 'report.xlsx')

ワークシート タブはディクショナリ順に表示され、最初のタブは RealmJoin オレンジ、残りのタブはニュートラル グレーで色付けされます。

カバー シート、ハイライト ルール、データ バー

情報カバー シート、色付きの状態列、セル内データ バーを備えた、完全な「レポート ブック」パターン:

$coverSheet = [ordered]@{
    Title             = 'Device Report'
    'Tenant'          = $tenantDisplayName
    'Generated (UTC)' = (Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm')
    'Runbook version' = $Version
    'Devices total'   = "$($devices.Count)"
}

Export-RjRbXlsx `
    -Worksheets      ([ordered]@{ 'Devices' = $devices }) `
    -Path            (Join-Path $env:TEMP 'device-report.xlsx') `
    -CoverSheet      $coverSheet `
    -HighlightRules  @(
        @{ Column = 'Compliant'; Value = 'yes'; Color = 'Green' },
        @{ Column = 'Compliant'; Value = 'no';  Color = 'Red' }
    ) `
    -DataBarColumns  @('AppCount')

カバー シートは、 Title の値を、オレンジのアクセント ライン上にある紺色の見出しとして配置し、その他のキーはすべてラベル/値の行として配置します。

親しみやすいハイパーリンク テキスト

URL 列は既定でクリック可能で、元の URL を表示します。列を親しみやすい表示テキストにマップして、テーブルを細く保てます。

$rows = $devices | Select-Object DeviceName, SerialNumber, @{
    n = 'Portal'
    e = { "https://intune.microsoft.com/#view/Microsoft_Intune_Devices/DeviceSettingsMenuBlade/~/overview/mdmDeviceId/$($_.id)" }
}

$rows | Export-RjRbXlsx -Path $xlsxPath -WorksheetName 'Devices' -HyperlinkText @{ Portal = 'Intune で開く' }

配信ヘルパーとの組み合わせ

レポート runbook でよくあるエンドツーエンドのパターン — ブックを書き出し、それをレポート メールに添付するか、ダウンロード リンク用にアップロードします。

$xlsxPath = Join-Path $env:TEMP 'report.xlsx'
Export-RjRbXlsx -Worksheets ([ordered]@{ Changes = $changeRows; 'All Users' = $allUserRows }) `
    -Path $xlsxPath -CoverSheet $coverSheet

# メール配信 — コンパクトなブックはサイズ制限のフォールバック添付に最適です
Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         $EmailTo `
    -Subject         "Report — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent $reportMd `
    -Attachments     @($xlsxPath)

# ...または、期限付きダウンロード リンクを使ったストレージ配信
$uploaded = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $xlsxPath `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -AddBlobNamePrefix  $true

参照: Send-RjRbReportEmail および Publish-RjRbFilesToStorageContainer このパターンの配信側に対して。

セル型の処理

入力値	次のようにレンダリングされます:
.NET の整数/浮動小数点/decimal 型	Excel の数値（必要に応じて -UseThousandsSeparator). NaN/Infinity はテキストにフォールバックします。
[datetime]	実際の Excel 日付。日付のみの値には日付書式が付き、時刻を含む値には日付時刻書式が付きます。表示クライアントによってローカライズされます。
ISO-8601 日付文字列（2026-07-16T08:00:00Z、典型的な Graph の日付フィールド）	解析され、実際に並べ替え可能な Excel 日付として表示されます。
[bool]	Excel のブール値（TRUE/FALSE).
http:// / https:// URL 文字列	クリック可能なハイパーリンク（非表示にするには -NoHyperlink; 表示テキストは -HyperlinkText).
配列 / コレクション	項目は ; で結合され、
$null / DBNull	空のセル。
それ以外すべて	プレーン テキスト。先頭/末尾の空白は保持されます。文字列が数値や数式として再解釈されることはありません。

動作とエラー処理

ワークシート名

ワークシート名は Excel の規則に合わせてサニタイズされます。無効な文字（[ ] : * ? / \）は置換され、名前は 31 文字に切り詰められ、空の名前は Sheet<n>になり、重複には _2, _3、… の接尾辞が付きます。

列ヘッダー

ヘッダー名は最初の行オブジェクトのプロパティ順から取得されます。空のプロパティ名は Column<n>になり、重複名（大小文字を区別しない）は _2, _3、… の接尾辞で重複排除されます。Excel のテーブル列は一意で空欄であってはならないためです。

空のワークシート

行セットが空のワークシートでも書き出されます。そこには 1 つの「No data available」セルだけがあり、テーブルはありません。ただし、空の -Worksheets ディクショナリは Export-RjRbXlsx: -Worksheets must contain at least one entry.

行数制限

Excel はワークシートを 1,048,576 行に制限します。この関数は Export-RjRbXlsx: worksheet '<name>' has <n> rows - the xlsx limit is 1048575 data rows. をスローして、無効なファイルが書き込まれるのを防ぎます。非常に大きな出力は複数のワークシートに分割するか、代わりに CSV として配信してください。

ハイライト ルール

• ワークシートに存在しない列を参照するルールは、そのワークシートでは静かにスキップされます（その列を持つ他のワークシートには引き続き適用されます）。
• 未知の Color 値は Export-RjRbXlsx: unknown highlight color '<color>' - use Green, Red or Yellow. Skipping rule. という警告を出し、そのルールだけをスキップします。

列幅

幅はヘッダーの長さと最初の 1,000 行のデータから計算され（8 文字から 60 文字の間に制限されます）、そのため非常に大きな出力でも幅計算で遅くなりません。

出力ファイル

既存の Path のファイルは削除されて再作成されます。この関数は親ディレクトリを自動作成しません。対象フォルダーが存在することを確認してください（例: New-Item -ItemType Directory).

出力

この関数は何も返しません。ブックを Path に書き込み、詳細メッセージ（Export-RjRbXlsx: wrote <n> worksheet(s) to <path>）を出力します。これは runbook が -Verbose または $VerbosePreference = 'Continue'.

関連項目

• Send-RjRbReportEmail — 生成したブックをレポート メールの添付として配信します。
• Publish-RjRbFilesToStorageContainer — ブックを Azure Blob Storage にアップロードし、期限付きダウンロード リンクを返します。
• Runbook レポート設定 — レポート配信チャネルの中心となる構成です。
• インライン使用例: sync-MFA-secure-users-to-group_scheduled.ps1 — モジュールに同梱されるまで、この関数を現在保持している runbook。