2.機能提供開始から廃止までとObsolete属性ここでは、クラスライブラリで一度提供を開始したメソッドをObsoleteとし、最終的に廃止するまでをリリース毎に考えていきます。機能の廃止や置き換えに関するリリースポリシーの一例としてご覧ください。最初のリリースでは以下のようにメソッドを提供したとします。<summary>文字列の並びを逆転した結果を返します。cref="System.String"/>を返します。2.実装に問題がある、より洗練された実装を提供するなどの理由により、今後のリリースではこのメソッドの利用を推奨しないことになったとします。これに従い、メソッドにObsolete属性を追加することによって利用者にその旨を通知します。同時に、代替となる新しいメソッドも用意します。<summary>文字列の並びを逆転した結果を返します。<remarks>このメソッドはサロゲートペアを含む文字列を正しく処理できません。cref="System.String"/>を返します。[Obsolete("このメソッドは推奨されません。文字列がサロゲートペアを含む場合はCodePointWiseReverse()を使用してください。<summary>文字列の並びを逆転した結果を返します。cref="System.String"/>を返します。<remarks>このメソッドはサロゲートペアを含む文字列でも正しく処理します。2.このとき、旧式メソッドと動作が変わらない代替メソッドを提供できる場合や、動作が変わっても問題ないと判断する場合は、旧式メソッドから代替メソッドを呼び出すようにして機能を完全に置き換えてしまうこともできます。<summary>文字列の並びを逆転した結果を返します。cref="System.String"/>を返します。[Obsolete("このメソッドは廃止予定です。CodePointWiseReverse()を使用してください。<summary>文字列の並びを逆転した結果を返します。cref="System.String"/>を返します。<remarks>このメソッドはサロゲートペアを含む文字列でも正しく処理します。2.次のリリースでは、これまでに廃止予定としたメソッドを廃止することになったとします。trueを追加してエラーとして扱うように変更します。<summary>文字列の並びを逆転した結果を返します。<remarks>このメソッドは廃止されました。CodePointWiseReverse()を使用してください。cref="System.String"/>を返します。"このメソッドは廃止されました。CodePointWiseReverse()を使用してください。<summary>文字列の並びを逆転した結果を返します。cref="System.String"/>を返します。<remarks>このメソッドはサロゲートペアを含む文字列でも正しく処理します。2.この時点で、利用者は旧式のメソッドを使うことができなくなり、代替メソッドを使用しなければならなくなります。Obsolete属性による警告・エラーは、コンパイル時にのみ発せられます。従って、ライブラリを参照するコンパイル済みのコードがある場合、ライブラリ側でObsolete属性が警告からエラーに変わったとしても、コンパイル済みコードの実行には影響しません。再コンパイルする時点で初めてエラーとして通知されます。実行可能ファイルを再コンパイルせず、コンパイル済みのライブラリだけを置き換えてバージョンアップするようなシナリオの場合、Obsolete属性のerrorパラメータがfalseからtrueに変わっても、引き続き旧式のメソッドが呼び出されることになります。旧式メソッドの廃止に伴い、実装も削除すると判断した場合は、次のように例外NotSupportedExceptionをスローするようにすることもできます。<summary>文字列の並びを逆転した結果を返します。<remarks>このメソッドは廃止されました。CodePointWiseReverse()を使用してください。cref="NotSupportedException">このメソッドを呼び出した場合にスローされます。"このメソッドは廃止されました。CodePointWiseReverse()を使用してください。NotSupportedException("このメソッドは廃止されました。CodePointWiseReverse()を使用してください。<summary>文字列の並びを逆転した結果を返します。cref="System.String"/>を返します。<remarks>このメソッドはサロゲートペアを含む文字列でも正しく処理します。2.errorパラメータをtrueにした時点で、新たにコンパイルするコードではエラーとなり、利用できない状態になります。コンパイル済みのコードからは依然として呼び出し自体は可能であるため、そういった呼び出しも禁止したい場合はこのように例外をスローするようにします。実装されていない旨を強調するために、NotSupportedExceptionではなくNotImplementedExceptionをスローすることも考えられます。NotImplementedExceptionでは今後実装される可能性のニュアンスを含むため、完全に廃止された機能の場合はどちらの例外がより妥当かどうかは判断が分かれます。Frameworkでは、ObsoleteExceptionやDeprecatedExceptionといったようなこの状況に適した例外クラスは用意されていません。十分な必要性があるなら、NotSupportedExceptionあるいはNotImplementedExceptionを継承してこのような例外クラスを作成し、スローするということも考えられます。ここまでの時点では、機能自体は廃止したものの、クラスライブラリのAPI互換性は維持されています。クラスライブラリのAPI互換性を破壊するようなリリースを行っても問題ないと判断する場合は、次のように完全にメソッド自体を削除した上でリリースすることもできます。"このメソッドは廃止されました。CodePointWiseReverse()を使用してください。NotSupportedException("このメソッドは廃止されました。CodePointWiseReverse()を使用してください。<summary>文字列の並びを逆転した結果を返します。cref="System.String"/>を返します。<remarks>このメソッドはサロゲートペアを含む文字列でも正しく処理します。2.ここまでの例でライブラリのバージョンを明記するために用いた属性AssemblyVersionについてはアセンブリのバージョン情報を取得するなどを参照してください。Obsolete属性とXMLドキュメントコメントC#やVB.NETでは、XMLドキュメントコメントによってメソッドの機能・動作・引数と戻り値の説明などを記述することができます。Javadocにおける@deprecatedタグのような廃止予定・非推奨となった旨を記述する要素、例えば<obsolete>や<deprecated>のような要素は定義されていません。そのため<summary>要素や<remarks>要素として記述する必要があります。(JavaScript)によれば、J#では<obsolete>要素、JavaScriptでは<deprecated>要素が定義されています。C#やVB.NETでもこういった要素を使った記述自体は行えますが、ドキュメントによって定義されていない要素のため、ビューアーやドキュメントジェネレータが対応していない限り、適切に表示されるとは限りません。§.XMLドキュメントコメントの要素を参照してください。