連載Index(読む順・公開済リンクが最新)
S00_門前の誓い_総合Index
C#のコードを読んでいると、こんな記述を見かけることがあります。
[Serializable]
public class User
{
[XmlIgnore]
public string Password { get; set; }
}
この、
[Serializable]
や、
[XmlIgnore]
のように [] で囲まれているものを、C#では Attribute(属性) と呼びます。
最初のうちは、
これ付いてるけど何が変わるの?
となりやすいところです。
この記事では、実務でよく見かけるAttributeを、
「何をしたいときに使うのか」
でまとめます。
全部覚える必要はありません。
「あ、この用途ならこのAttributeだったな」
くらいで十分です。
まずはこれだけ
よく見るものを先にまとめます。
| やりたいこと | Attribute |
|---|---|
| XMLに出したくない | [XmlIgnore] |
| JSONに出したくない | [JsonIgnore] |
| JSONの項目名を変えたい | [JsonPropertyName] |
| 入力必須にしたい | [Required] |
| 文字数を制限したい | [StringLength] |
| PropertyGridに表示したくない | [Browsable(false)] |
| DBに保存したくない | [NotMapped] |
| 古いメソッドを使わせたくない | [Obsolete] |
| デバッグ画面を見やすくしたい | [DebuggerDisplay] |
| WindowsのDLLを呼びたい | [DllImport] |
まずはこのあたりを知っておけば、かなりコードを読みやすくなります。
そもそもAttributeって何?
ざっくり言うと、
クラスやプロパティに「追加の情報」を付けるもの
です。
例えば、
[Obsolete]
public void OldMethod()
{
}
と書くと、
このメソッドは古いですよ
という情報を付けられます。
その情報を、コンパイラやライブラリ、フレームワークなどが読み取ります。
イメージとしてはこんな感じです。
プロパティ
↓
Attributeを付ける
↓
「これはJSONに出さないで」
「これはDBに保存しないで」
「これは画面に表示しないで」
↓
各ライブラリがその情報を読む
Attribute自体が何か処理をする、というより、
「こう扱ってください」という札を付ける
と考えると分かりやすいです。
XMLに関するAttribute
XMLファイルを読み書きするときに使います。
名前空間は主にこちらです。
System.Xml.Serialization
XmlIgnore
XMLに出したくない項目に付けます。
public class User
{
public string Name { get; set; }
[XmlIgnore]
public string Password { get; set; }
}
この場合、Password はXMLに保存されません。
例えば、
<User>
<Name>Taro</Name>
</User>
のようになります。
こんなときに使う
- XMLに保存したくない値
- 実行中だけ使う値
- パスワードなど保存したくない情報
XmlElement
XMLに出力するときの名前を変更できます。
[XmlElement("user_name")]
public string Name { get; set; }
出力すると、
<user_name>Taro</user_name>
のようになります。
C#側では Name だけど、XMLでは user_name にしたい。
そんなときに使います。
XmlAttribute
XMLの「要素」ではなく「属性」として出力します。
[XmlAttribute("id")]
public int Id { get; set; }
例えば、
<User id="1">
</User>
のようになります。
XmlRoot
XMLの一番外側の名前を変更します。
[XmlRoot("user")]
public class User
{
}
JSONに関するAttribute
最近の.NETでは System.Text.Json を使うことが多いです。
名前空間はこちらです。
System.Text.Json.Serialization
JsonIgnore
JSONに出したくない項目に付けます。
public class User
{
public string Name { get; set; }
[JsonIgnore]
public string Password { get; set; }
}
JSONにすると、
{
"Name": "Taro"
}
となり、Password は出力されません。
XmlIgnoreとの違い
ここはよく混乱します。
[XmlIgnore]
はXML用。
[JsonIgnore]
はJSON用です。
同じ「出力しない」でも、相手が違います。
JsonPropertyName
JSONに出すときの名前を変更します。
[JsonPropertyName("user_name")]
public string Name { get; set; }
すると、
{
"user_name": "Taro"
}
になります。
APIとの通信などでよく使います。
JsonConverter
JSONへの変換方法を変更したいときに使います。
[JsonConverter(typeof(MyDateTimeConverter))]
public DateTime CreatedAt { get; set; }
例えば、
- 日付の形式を変更したい
- enumの出し方を変えたい
- 独自形式の値を扱いたい
といったときに使います。
これは少し応用寄りです。
入力チェックに使うAttribute
フォーム入力やAPIの入力値チェックなどでよく使います。
主にこちらの名前空間です。
System.ComponentModel.DataAnnotations
Required
入力必須にしたい項目に付けます。
[Required]
public string Name { get; set; }
「名前は必須」という意味になります。
StringLength
文字数を制限します。
[StringLength(20)]
public string Name { get; set; }
最大20文字です。
最小文字数も指定できます。
[StringLength(20, MinimumLength = 3)]
public string Name { get; set; }
この場合は、
3文字以上20文字以下
です。
Range
数値の範囲を指定します。
[Range(0, 120)]
public int Age { get; set; }
0~120の間だけ有効、という意味です。
EmailAddress
メールアドレス形式をチェックします。
[EmailAddress]
public string Email { get; set; }
RegularExpression
正規表現を使って入力内容をチェックします。
[RegularExpression(@"^[0-9]+$")]
public string Number { get; set; }
この例では数字だけを許可しています。
PropertyGridや画面表示で使うAttribute
WinFormsを触っていると、かなり見かけます。
主にこちらです。
System.ComponentModel
Browsable
PropertyGridに表示するかどうかを指定します。
[Browsable(false)]
public string InternalValue { get; set; }
false にするとPropertyGridには表示されません。
こんなときに使う
- publicにはしたい
- でも利用者には変更させたくない
- PropertyGridには表示したくない
Category
PropertyGrid上の分類を指定します。
[Category("表示")]
public string Title { get; set; }
PropertyGridで「表示」というグループにまとめられます。
Description
PropertyGridなどに説明文を表示します。
[Description("画面上部に表示するタイトルです。")]
public string Title { get; set; }
利用者がプロパティの意味を理解しやすくなります。
DisplayName
画面上で表示する名前を変更します。
[DisplayName("タイトル")]
public string Title { get; set; }
C#では Title だけど、画面上では「タイトル」と表示できます。
ReadOnly
PropertyGridなどで編集できないようにします。
[ReadOnly(true)]
public string Id { get; set; }
注意したいのは、
[ReadOnly(true)]
と、
readonly
は別物ということです。
Attributeの ReadOnly は、主に画面側での編集可否を伝えます。
DefaultValue
既定値を表す情報を付けます。
[DefaultValue(100)]
public int Width { get; set; }
ただし、これだけでは自動的に 100 が代入されるわけではありません。
実際に100を初期値にするなら、
[DefaultValue(100)]
public int Width { get; set; } = 100;
のように書きます。
ここは少し間違えやすいところです。
DBに関するAttribute
Entity Frameworkなどで使います。
Key
主キーを指定します。
[Key]
public int Id { get; set; }
Table
使用するテーブル名を指定します。
[Table("Users")]
public class User
{
}
Column
使用するカラム名を指定します。
[Column("USER_NAME")]
public string Name { get; set; }
NotMapped
DBに保存したくないプロパティに付けます。
[NotMapped]
public string DisplayName { get; set; }
例えば、
public string FirstName { get; set; }
public string LastName { get; set; }
[NotMapped]
public string FullName => $"{LastName} {FirstName}";
のような場合です。
FullName は計算で作れるので、DBに保存する必要がありません。
ForeignKey
外部キーを指定します。
[ForeignKey(nameof(Department))]
public int DepartmentId { get; set; }
テーブル同士の関連を指定するときに使います。
古いコードだとよく見るAttribute
Serializable
[Serializable]
public class User
{
}
クラスをシリアライズ可能なものとして扱うためのAttributeです。
昔の.NET Frameworkのコードではよく見かけます。
ただし、最近のJSON保存などでは、
[Serializable]
が必須というわけではありません。
例えば System.Text.Json でJSON化するときは、通常付けなくても動きます。
そのため、
シリアライズするならとりあえずSerializable
と考えない方がいいです。
NonSerialized
シリアライズしたくないフィールドに付けます。
[NonSerialized]
public string TemporaryValue;
こちらも古い.NET Framework系のコードで見かけることがあります。
古いメソッドを使わせたくない
Obsolete
古くなったメソッドやクラスに付けます。
[Obsolete]
public void OldMethod()
{
}
呼び出すとVisual Studioで警告が出ます。
メッセージも付けられます。
[Obsolete("NewMethodを使用してください。")]
public void OldMethod()
{
}
こうしておくと、
このメソッド古いんだな
新しい方を使えばいいんだな
と分かります。
実務でもかなり便利です。
デバッグを見やすくするAttribute
DebuggerDisplay
デバッグ中の表示を分かりやすくできます。
[DebuggerDisplay("{Id}: {Name}")]
public class User
{
public int Id { get; set; }
public string Name { get; set; }
}
通常だとデバッガーで、
User
のようにしか見えないところを、
1: Taro
のように表示できます。
Listの中身を見るときなど、かなり便利です。
WindowsやC++のDLLを呼ぶとき
少し応用ですが、古い業務システムや制御系ではよく見かけます。
名前空間はこちらです。
System.Runtime.InteropServices
DllImport
Windows APIやC/C++のDLLを呼び出すときに使います。
[DllImport("user32.dll")]
private static extern int MessageBox(
IntPtr hWnd,
string text,
string caption,
uint type);
StructLayout
C/C++側の構造体とメモリ配置を合わせたいときに使います。
[StructLayout(LayoutKind.Sequential)]
public struct UserData
{
public int Id;
public int Age;
}
制御系や装置通信などでは割とよく出てきます。
MarshalAs
C#とC/C++でデータ型の扱いが違う場合に指定します。
[MarshalAs(UnmanagedType.LPWStr)]
public string Name;
このあたりはInteropを扱うようになってから覚えれば十分です。
名前を自動で取得するAttribute
ログ処理などで便利です。
CallerMemberName
呼び出したメソッド名を自動取得できます。
public void WriteLog(
string message,
[CallerMemberName] string memberName = "")
{
Console.WriteLine($"{memberName}: {message}");
}
例えば、
public void Save()
{
WriteLog("保存開始");
}
とすると、
Save: 保存開始
のように、呼び出し元のメソッド名を自動で取得できます。
CallerLineNumber
呼び出した行番号を取得できます。
public void WriteLog(
string message,
[CallerLineNumber] int lineNumber = 0)
{
}
CallerFilePath
呼び出したファイル名を取得できます。
public void WriteLog(
string message,
[CallerFilePath] string filePath = "")
{
}
ログを作るときに便利です。
一番混乱しやすいところ
次のAttributeは全部、
このプロパティを使わないで
という意味に見えます。
でも実際はそれぞれ別物です。
| Attribute | 何から外す? |
|---|---|
[XmlIgnore] |
XML |
[JsonIgnore] |
JSON |
[NotMapped] |
DB |
[Browsable(false)] |
PropertyGrid |
[NonSerialized] |
一部のシリアライズ |
例えば、
[XmlIgnore]
[JsonIgnore]
[NotMapped]
[Browsable(false)]
public string TemporaryValue { get; set; }
のように複数付くこともあります。
これは同じ意味を4回書いているわけではありません。
それぞれ、
XMLには出さない
JSONにも出さない
DBにも保存しない
PropertyGridにも表示しない
という別々の指定です。
ここが分かると、Attributeがかなり理解しやすくなります。
Attributeを見たら「誰が読むのか」を考える
知らないAttributeを見つけたときは、
「これは誰が読むAttributeなんだろう?」
と考えるのがおすすめです。
例えば、
[JsonIgnore]
ならJSONを扱うライブラリ。
[NotMapped]
ならEntity Framework。
[Browsable(false)]
ならPropertyGrid。
[DebuggerDisplay]
ならVisual Studioのデバッガー。
この考え方をすると、かなり整理しやすくなります。
まとめ
C#のAttributeはかなり種類があります。
全部覚える必要はありません。
まずは、
XML
JSON
入力チェック
PropertyGrid
DB
デバッグ
DLL連携
くらいに分けて覚えておくと十分です。
特によく見るのはこのあたりです。
[XmlIgnore]
[JsonIgnore]
[Required]
[Browsable(false)]
[NotMapped]
[Obsolete]
[DebuggerDisplay]
コードを読んでいて知らないAttributeが出てきたら、
「このAttributeは誰が読むのか?」
を確認すると、その役割がかなり分かりやすくなります。
Attributeは難しい仕組みに見えますが、最初は、
「このプロパティをこう扱ってください、という札」
くらいに考えておけば大丈夫です。
連載Index(読む順・公開済リンクが最新)
S00_門前の誓い_総合Index