PowerShellの.NET入門:日時が変わらない理由と戻り値の扱い

PowerShellの.NET操作を、型からの静的呼出し、日時の戻り値、StringBuilderの内容変更の3点で整理した独自図解。

PowerShellで5日後を求めても、元の日付が変わらないことがあります。日時を表すDateTimeのAddDaysは新しい日時を返すため、結果を受け取る必要があります。この返ってくる値が「戻り値」です。

本稿では日時の作成から始め、型から呼ぶ操作と、作成した値への操作を読み分けます。型は日時や文字列といった値の種類、.NETはそうした型と機能を提供する基盤です。

対象はWindows PowerShell 5.1です。管理者権限や追加インストールは不要です。掲載例はメモリ内の日時と架空の文字列だけを扱い、ファイルやシステム設定を変更しません。

先に結論

  • 型から呼ぶ操作は二重コロン、作成済みの値の情報や操作はドットで読み分けます。
  • DateTimeのAddDaysは新しい日時を返します。結果を受け取り、取得専用のYearへは代入しません。
  • StringBuilderのAppendは内容を変更します。戻り値の表示を抑えても、操作そのものは実行されます。

1.Windows PowerShellを開いて版を確認する

1行目が5.1で始まり、2行目がDesktopなら本稿の対象です。

Windowsのスタートメニューで「Windows PowerShell」を検索し、通常の権限で開きます。Windows PowerShell 5.1は.NET Frameworkを基盤としており、本稿はこの環境で進めます。

下の欄にあるPSVersionTableは、実行中のPowerShellの情報を持つ変数です。変数は値を一時的に保持する名前で、先頭にドル記号を付けます。PSVersionは版、PSEditionは種類を示します。

掲載例の実行結果はWindows PowerShell 5.1 Desktopのものです。PowerShell 7は別の.NET基盤を使い、使える機能は版やOSで異なります。PowerShell 7、macOS、Linuxでの結果は未確認です。

  1. 下の2行を両方貼り付け、最後の行でEnterを押します。
  2. 1行目の版と2行目の種類を確認します。5.1で始まる版とDesktopの組み合わせなら、次の節へ進めます。
  3. 異なる場合は、開いたアプリがWindows PowerShellか確認します。設定変更で合わせようとせず、対象の画面で作業を進めてください。

PowerShellの版と種類を確認する

$PSVersionTable.PSVersion.ToString()
$PSVersionTable.PSEdition

実行結果

5.1.26100.9818
Desktop

表示例の5.1に続く細かい番号は環境によって異なります。ToStringは値を文字列へ変える操作で、ここでは版番号を読みやすい形で表示しています。

以降も同じ画面で、各コード欄を先頭から末尾まで貼り付け、最後の行でEnterを押します。途中の行だけでは、値の準備や結果の表示が抜けることがあります。

改行待ちの表示が続く場合は、Ctrl+Cで入力を中止し、欄の先頭から貼り付け直してください。複数行に分かれた処理も、欄の最後までを実行対象にします。

スマートフォンでコードの右側が切れる場合は、コード欄を横へスクロールし、行末まで確認してから実行してください。

2.newとNew-Objectで同じ日時を作る

年月日を指定して日時を作り、型・日付・一致の順に確認します。

オブジェクトは、型に従って作られた具体的な値です。その一つをインスタンスとも呼びます。型にはクラスや構造体などがあり、日時を表すSystem.DateTimeは構造体です。

newは、型を指定して値を作るための書き方です。この作成処理をコンストラクター、作成に渡す値を引数と呼びます。最初の行では、2026年11月18日の年月日を順に渡します。

型名を囲む角括弧は型を指します。二重コロンでnewにつなぎ、丸括弧の中に引数をカンマで区切って渡します。等号は、右の結果を左の変数へ入れる代入の記号です。

newの書き方はPowerShell 5.0以降で使えます。続くNew-ObjectはPowerShellの標準命令で、同じ日時を別の変数へ作ります。下の欄は、一致を比較する最後の行まで実行してください。

同じ日時を2通りで作る

$day = [System.DateTime]::new(2026, 11, 18)
$legacy = New-Object -TypeName System.DateTime -ArgumentList 2026, 11, 18
$day.GetType().FullName
$day.ToString('yyyy-MM-dd')
$day -eq $legacy

実行結果

System.DateTime
2026-11-18
True

出力はSystem.DateTime、2026-11-18、Trueの3行です。最初の2行はday変数の型と日付、最後の行はday変数とlegacy変数の日時が等しいことを示します。

GetTypeは型を調べる操作、FullNameは型の正式名を読む項目です。日付を表示するToStringのyyyy-MM-ddは、年・月・日を固定の形で表示する指定です。

New-ObjectのTypeNameとArgumentListは、命令へ条件を渡すパラメーターです。それぞれ作る型と引数を指定し、名前の先頭にハイフンを付けます。

最後の行のeqは、ハイフン付きで書く比較の記号です。Trueは日時の値が等しいことを表します。同じ一つのオブジェクトを指しているかを調べる判定ではありません。

3.引数なしで作った日時は現在時刻にならない

日時の初期値と、現在時刻を取得するNowを区別します。

前節のNew-Objectで年月日の引数を省くと、現在時刻にはなりません。下の欄では、まず引数なしで作った日時を表示し、その後にNowから得る現在時刻の型を表示します。

プロパティは、値や型に備わる情報を表す項目です。Nowは型から現在時刻を読むプロパティなので、型名と二重コロンでつなぎます。現在時刻そのものは表示せず、どの型の値かを確認します。

引数なしの日時は現在時刻ではない

$emptyDay = New-Object -TypeName System.DateTime
$emptyDay.ToString('yyyy-MM-dd')
[System.DateTime]::Now.GetType().FullName

実行結果

0001-01-01
System.DateTime

1行目の0001-01-01は、引数を指定せず作ったDateTimeの初期値です。特定の日付を用意したい場合は、第2節のように年月日を指定してください。

2行目のSystem.DateTimeは、Nowで得た現在時刻の型です。現在時刻の値は実行のたびに変わるため、掲載例では値を固定せず、型だけを確認しています。

4.ドットで年を読み、利用できる操作を調べる

情報を表すプロパティと、処理を行うメソッドを区別します。

作成した日時の年を読むには、day変数とYearをドットでつなぎます。ドットは、左側の値が持つ項目へアクセスする記号です。Yearは、年の情報を表すプロパティです。

メソッドは、計算や変換などを行う操作です。GetTypeやToStringもメソッドで、呼び出すときに丸括弧を付けます。プロパティとメソッドをまとめて、メンバーと呼びます。

Get-Memberは、その値のメンバーを調べる命令です。下の欄ではInputObjectに日時、Nameに調べる名前を指定し、AddDaysとYearだけを取り出して「名前: 種類」と表示します。

縦棒は左の結果を右へ渡す記号です。Sort-ObjectはNameの順に並べ、ForEach-Objectは各項目を1件ずつ処理します。複数行に分かれた末尾の処理まで、まとめて実行してください。

日時の項目と操作を調べる

$day = [System.DateTime]::new(2026, 11, 18)
$day.Year
Get-Member -InputObject $day -Name AddDays, Year |
    Sort-Object -Property Name |
    ForEach-Object { '{0}: {1}' -f $_.Name, $_.MemberType }

実行結果

2026
AddDays: Method
Year: Property

出力は2026、AddDays: Method、Year: Propertyの3行です。Methodは操作、Propertyは情報を表します。Propertyと分かっても、値を書き換えられるかまでは判断できません。

末尾の処理にある、ドル記号とアンダースコアの組み合わせは、処理中の1件を表します。ハイフン付きのfは、左の書式にある番号付きの波括弧へ、右側の値を順に入れる指定です。

この例では、名前を0番目、種類を1番目の位置へ入れ、間にコロンを置いています。メソッドの戻り値やプロパティの書込み可否は、調べた名前を手掛かりに公式仕様で確認します。

5.二重コロンで型から操作を呼び出す

静的な操作は、作成済みのインスタンスを用意せずに呼び出せます。

静的とは、作成済みのインスタンスを用意せず、型から呼び出せることです。下の欄ではSystem.MathのSqrtで81の平方根を求め、DateTimeのIsLeapYearで2028年がうるう年かを調べます。

次の比較表は、作成・情報の取得・操作を読み分けるためのものです。左側が型なのか、作成済みの値なのかを確かめてください。表にあるAddDaysの具体的な出力は、次の節で確認します。

書き方 対象 例で分かること
[型名]::new(引数) 指定した型から作成 2026-11-18の日時を作る
$day.Year 作成済みの日時の情報 年2026を読む
$day.AddDays(5) 作成済みの日時への操作 5日後の新しい日時が返る
[System.Math]::Sqrt(81) 型の静的な操作 平方根9を返す

型から静的メソッドを呼ぶ

[System.Math]::Sqrt(81)
[System.DateTime]::IsLeapYear(2028)

実行結果

9
True

1行目の9は81の平方根です。9を2回掛けると81になります。2行目のTrueは、2028年がうるう年であることを示します。どちらも作成済みの日時を用意せずに呼び出しています。

二重コロンだけでメソッドとは判断しません。Nowのような静的プロパティもあります。SqrtとIsLeapYearは呼出し用の丸括弧を付け、情報を読むNowには丸括弧を付けません。

6.AddDaysの結果を受け取り、元の日時と比べる

AddDaysは元の日時を変えず、加算後の新しい日時を返します。

DateTimeのAddDaysへ渡す5は、加える日数です。5日後の日時は戻り値として返るため、必要な変数へ受け取ります。操作を呼んだだけでは、元の日時は変わりません。

下の欄では11月18日の日時をday変数へ入れ、5日後をnext変数へ受け取ります。元の日時と計算結果を並べた後、day変数にも結果を代入します。末尾の日付表示まで実行してください。

AddDaysの戻り値と元の日時を並べる

$day = [System.DateTime]::new(2026, 11, 18)
$next = $day.AddDays(5)
$day.ToString('yyyy-MM-dd')
$next.ToString('yyyy-MM-dd')
$day = $day.AddDays(5)
$day.ToString('yyyy-MM-dd')

実行結果

2026-11-18
2026-11-23
2026-11-23

3行の出力は、元の2026-11-18、計算結果の2026-11-23、再代入後の2026-11-23です。day変数へ受け取り直す前後で、表示される日付が変わります。

元の日付も必要なら、next変数のように別の変数へ結果を残します。更新後の日時をday変数で扱いたい場合は、その変数へ結果を受け取り直します。

7.Yearは取得専用なので直接代入できない

年を変えた日時が必要なら、年月日を指定して作り直します。

Yearは年を読むための取得専用プロパティです。取得専用とは、情報を読めても直接書き換えられないことです。下の欄は先頭で11月18日を作り直すため、前節の結果には依存しません。

この欄ではYearへ2030を代入しようとします。tryの波括弧の内側で処理し、失敗するとcatchの波括弧の内側へ進みます。最後に日付を表示し、元の値が残ることを確かめます。

Yearを変更しようとした場合を確認する

$day = [System.DateTime]::new(2026, 11, 18)
try {
    $day.Year = 2030
} catch {
    'Yearは直接変更できません。'
}
$day.ToString('yyyy-MM-dd')

実行結果

Yearは直接変更できません。
2026-11-18

「Yearは直接変更できません。」に続いて2026-11-18が表示されます。この例ではYearへの代入が失敗し、日付は変わっていません。案内文の後の日付表示まで確認してください。

年を変えた日時が必要なら、第2節の方法で必要な年月日を指定して作り直します。プロパティはすべて書き換え可能とは限らないため、情報の意味に加えて書込み可否も確認します。

8.StringBuilderは戻り値を表示しなくても内容が変わる

戻り値の表示を抑えることと、操作を止めることは別です。

StringBuilderは、文字列を組み立てるための型です。Appendは作成したオブジェクトへ文字列を追加し、その同じオブジェクトを戻り値として返します。DateTimeのAddDaysとは、元の内容が変わるかが異なります。

下の欄は「品目:」で作成し、「ノート」を追加します。続けて内容と長さを表示し、Clearで内容を空にします。最後のLengthの表示まで実行すると、追加前後ではなく、追加後と消去後の長さを確認できます。

コードにあるnullは、先頭にドル記号を付けて書く特別な変数です。値がないことを表し、これを代入先にすると戻り値の表示を抑えられます。AppendやClearの実行そのものは止まりません。

StringBuilderで内容が変わる操作を確認する

$builder = [System.Text.StringBuilder]::new('品目:')
$null = $builder.Append('ノート')
$builder.ToString()
$builder.Length
$null = $builder.Clear()
$builder.Length

実行結果

品目:ノート
6
0

出力は「品目:ノート」、6、0の順です。6は追加後のLength、0はClearで空にした後のLengthです。戻り値を表示しなくても、内容の追加と消去は行われています。

Lengthは.NETの文字列の長さの数え方による値です。絵文字などでは、見た目の文字数と一致しない場合があります。この例の6という結果を、すべての文字列へ一般化しないでください。

最初からやり直すには、この欄を先頭から実行して新しく作ります。本稿では処理速度を比較していないため、速さを理由にStringBuilderへ置き換える判断までは扱いません。

9.存在しない日付では作成を止める

失敗の案内と、変数に値が残っていないことを確認します。

年月日の順が合っていても、存在しない日付は作成できません。下の欄は2026年2月30日を指定する失敗例です。作成に失敗するとcatchへ進み、年月日を確認する案内を表示します。

作成前にinvalid変数をnullへ戻すのは、以前の成功値を誤って使うことを防ぐためです。日時を作れた場合だけ成功の案内が表示されます。最後の比較行まで実行し、失敗後の値を確認してください。

存在しない日付では作成を中止する

$invalid = $null
try {
    $invalid = [System.DateTime]::new(2026, 2, 30)
    '作成できました。'
} catch {
    '日付を作れません。年月日を確認してください。'
}
$null -eq $invalid

実行結果

日付を作れません。年月日を確認してください。
True

案内文に続くTrueは、invalid変数がnullのままであることを示します。「作成できました。」は表示されません。ここでは、存在しない日付で作成が失敗することが想定どおりの結果です。

Falseが出るなど結果が異なる場合は、その変数を使う後続操作へ進まず、同じ画面で欄の先頭から実行し直してください。型名、年月日の順、末尾の比較行まで貼り付けたかを確認します。

10.結果が違うときは症状から確認する

作成の失敗、戻り値の受取り、内容の変更を分けて確認します。

結果が想定と違うときは、症状に合う項目から確認します。下の比較表では、元の値や内容が変わるかと、戻り値をどう扱うかを並べています。日時と文字列の出力へ戻るための確認用です。

型が見つからない場合も、外部から得た型名や命令をそのまま実行しないでください。DLLと呼ばれるプログラム部品についても、不明なものを追加して解消しようとせず、版やOSの対応範囲を確認します。

  • 型が見つからない:型名のつづりを確認し、第1節の版と種類、公式資料の対象OSを確かめます。
  • 日時を作れない:年・月・日の順と、実在する日付かを確認します。第9節の失敗例で入力と案内を読み直せます。
  • 計算後も日時が変わらない:第6節を参照し、AddDaysの結果を必要な変数へ受け取っているか確認します。
  • Yearへ代入できない:取得専用です。第7節を確認し、第2節の年月日を指定する作成方法へ戻ります。
  • 表示を抑えたのに文字列が変わる:Appendは実行されています。第8節で、戻り値の表示と内容変更を分けて確認します。
操作 元の値・内容 戻り値の扱い
$day.AddDays(5) 元の日時は変わらない 変更後の日時を変数へ受け取る
$day.Year = 2030 取得専用なので失敗 Yearへ直接代入しない
$builder.Append('ノート') 同じStringBuilderの内容が変わる 同じオブジェクトが返るので不要なら$nullへ
$builder.Clear() 同じStringBuilderの内容が空になる 不要な戻り値は$nullへ

作業を終えるときは、この記事用に開いた画面を閉じます。画面内の変数は残りません。他の作業と同じ画面を利用中の場合は、必要な処理を終えてから閉じてください。