CS0～400

C# コンパイラエラー CS0221 について解説

2025-03-29更新日: 2025-03-29

CS0221は、定数式の型変換によってデータ損失の可能性が検出された場合に出るC#のコンパイラエラーです。

既定で有効なcheckedコンテキストにより、例えば0xFFFFFFFFをint型にキャストする際にエラーが発生します。

エラーを解消するには、キャストの方法を見直すか、uncheckedキーワードを使用してください。

目次から探す

エラーの基本概要
- CS0221エラーとは
- エラーが発生する条件
定数式と型変換の詳細
- 定数式における型変換のルール
- checked と unchecked の違い
コード例による解析
開発環境での注意点
- コンパイラオプションの確認方法
- IDE上でのエラーチェック手法
まとめ

エラーの基本概要

CS0221エラーとは

CS0221エラーは、定数式に対して行われる型変換がデフォルトの checked 状態によって検出されるエラーです。

つまり、コンパイラが定数の値を変換する際に、データ損失が発生する可能性がある場合に、このエラーが発生します。

特に、定数リテラルの値を変換して対象となる型で表現できないときに報告されます。

例えば、 $int$ 型の範囲を超える値をInt32に変換しようとすると、CS0221エラーが表示されます。

エラーが発生する条件

エラーが発生する条件は以下の通りです。

定数式に対して値を型変換する際、変換後の型で値を正確に表現できない場合
デフォルトの「checked」状態が有効な環境で、オーバーフローが発生する可能性がある場合

例えば、16進数リテラルの値を $int$ 型にキャストしようとすると、値が $int.MaxValue$ を超える可能性があるとエラーが発生します。

定数式と型変換の詳細

定数式における型変換のルール

定数式の型変換では、コンパイラがコンパイル時に値の正確性をチェックします。

ここでは、以下のポイントに注意する必要があります。

定数式は、コンパイル時に評価可能な式である必要があります。
評価結果が変換先の型の範囲に収まるかどうかをチェックし、収まらない場合はエラーとして報告されます。
$int$ や $long$ などの数値型に対して不正な変換を行おうとすると、エラー CS0221 が発生します。

このルールは、プログラムの実行前に潜在的なデータ損失を防ぐための安全策となっています。

checked と unchecked の違い

checked 文の役割

checked文は、定数式や数値演算においてオーバーフローが発生しないかをチェックするために使います。

checked 状態下では、値が変換先の型の範囲外であった場合に例外が発生するか、コンパイルエラーとして検出されます。

例えば、次の例のように、デフォルトでは checked 状態が有効です。

定数式の変換で対象の型に収まらない場合に、エラーを出すことで意図しないデータ損失を防ぐ役割を果たします。

unchecked 文の活用方法

unchecked文を使用すると、型変換や数値演算がオーバーフローしてもエラーにならず、単に値がラップアラウンドされる処理が行われます。

unsafeな状況ではありますが、必要に応じて意図的にオーバーフローを許容する場合に利用できます。

次のサンプルコードは、unchecked を利用して変換エラーを回避する例です。

using System;
public class Program
{
    public static void Main()
    {
        // unchecked ブロック内ではオーバーフローしても例外やエラーが発生しません
        unchecked
        {
            int sampleValue = (int)0xFFFFFFFF;  // このキャストではオーバーフローが起こります
            Console.WriteLine("sampleValue = " + sampleValue);
        }
    }
}

sampleValue = -1

このコードでは、16進数リテラル 0xFFFFFFFF を int型にキャストしています。

unchecked ブロックを使用しているため、オーバーフローが検出されず、結果としてラップアラウンドして -1 になっています。

コード例による解析

エラー発生サンプルコードの解説

以下のサンプルコードは、CS0221エラーが発生する例を示しています。

定数式をそのままキャストした場合、値が int型に収まらないためエラーが発生します。

using System;
public class ErrorSample
{
    public static void Main()
    {
        // checked 状態で定数式をキャストするとオーバーフローが検出されてエラーになります
        int a = (int)0xFFFFFFFF;  // このキャストにより CS0221 エラーが発生します
        Console.WriteLine("a = " + a);
    }
}

// コンパイルエラー: 定数値 0xFFFFFFFF は int 型に変換できません

エラー部分の詳細説明

上記のコードでエラーが発生する理由は、定数リテラル 0xFFFFFFFF が 32 ビット符号あり整数の範囲( $- 2^{31}$ から $2^{31} - 1$ )を超えるためです。

checked 状態では、定数式の評価時点で値が変換先の型の範囲内かが検査され、収まらなければエラーと判断されます。

コード内のキャスト (int)0xFFFFFFFF が、この検査に引っかかってエラー CS0221 を生じさせています。

修正前後の比較

エラーが発生するコードと、unchecked ブロックを利用してエラーを回避するコードの違いを比較します。

修正前(エラー発生):

using System;
public class ErrorSample
{
    public static void Main()
    {
        int a = (int)0xFFFFFFFF;  // オーバーフローによる CS0221 エラー
        Console.WriteLine("a = " + a);
    }
}

// コンパイルエラー: 定数値 0xFFFFFFFF は int 型に変換できません

修正後(unchecked を利用):

using System;
public class FixedSample
{
    public static void Main()
    {
        // unchecked ブロックを使用することでオーバーフローチェックを回避します
        unchecked
        {
            int a = (int)0xFFFFFFFF;  // オーバーフローが発生しますがエラーになりません
            Console.WriteLine("a = " + a);
        }
    }
}

a = -1

修正前のコードはデフォルトの checked 状態により、キャスト時に値の不正な変換を検出してエラーとなります。

一方、修正後のコードは unchecked ブロックによりオーバーフローが許容され、結果としてラップアラウンドした値が出力されます。

開発環境での注意点

コンパイラオプションの確認方法

コンパイラオプションにより、既定の checked/unchecked の動作が変更されている可能性があります。

開発環境のプロジェクト設定や、ビルドスクリプトに指定されたコンパイラオプションを確認し、必要に応じて以下の点をチェックしてください。

Visual Studio のプロジェクトプロパティから「ビルド」設定内で、オーバーフローチェックの有無を確認する。
コマンドラインビルドの場合、コンパイラオプション /checked や /unchecked の指定を確認する。

これによって、定数式の評価がどのように行われるかを把握できます。

IDE上でのエラーチェック手法

多くのIDEは、コンパイル前にエラーや警告を表示してくれる機能を備えています。

以下の手法でエラーの原因や発生箇所を特定してください。

エディタのインラインエラー表示を利用して、エラー箇所にカーソルを合わせ、詳細情報を確認する。
ソリューションエクスプローラーからビルドエラー一覧を確認し、CS0221エラーが報告されている箇所を特定する。
必要に応じて、IDEの設定で checked/unchecked の動作に関するオプションを確認し、想定通りの挙動になっているかをチェックする。

以上の手法を利用して、開発環境内でエラー原因の調査と対処を進めると、より効率的なデバッグが可能となります。

まとめ

この記事では、CS0221エラーの概要と発生条件、定数式の型変換ルールについて解説しています。

チェック状態(checked)と許容状態(unchecked)の違いや、その活用方法を具体的なコード例とともに説明し、エラー発生箇所の詳細や修正前後の比較を行いました。

さらに、開発環境におけるコンパイラオプションやIDEのエラーチェック方法についても紹介し、エラー原因の特定と対処の一助となる内容になっています。C# コンパイラエラー CS0221 について解説