docs.microsoft.com での .NET リファレンス エクスペリエンスの統一のお知らせ

  • [アーティクル]

この記事は、Azure 展開およびエコシステム チームの統括部長、Jeff Sandquist によって執筆されました。

約 1 年前、docs.microsoft.com に .NET Core 参照文書を試験的に公開しました。 このたび、.NET API の参照方法が統一されたことをお知らせいたします。 マニアの開発者からスタートアップ、そして企業に至るまで、開発者の生産性が重要であることを私たちは理解しています。 この点を念頭に置いて、私たちは、Xamarin チームと密接に連携して、Microsoft で .NET API を文書化、検出、および移動する方法を標準化しています。

すべての .NET ドキュメントを 1 か所に

以前は、Microsoft から出荷される .NET ベースの SDK を見つけたい場合、それをダウンロードできる場所と、関連する API ドキュメントの両方をお気に入りの検索エンジンを使用して検索を試みる必要がありました。

今後は、すべての .NET 互換 SDK を 1 か所 (https://docs.microsoft.com/dotnet/api) に統合して検索できるようにする予定です。 そこには、.NET Framework、.NET Core、.NET Standard、および Xamarin のリファレンス ドキュメントと、Azure NuGet パッケージのドキュメントがあります。 今後数か月以内に、このエクスペリエンスにさらに SDK を追加する予定です。

API ブラウザーの概要

私たちの主な目標は、Web ブラウザーからすべての .NET API を検索できるように IntelliSense のようなエクスペリエンスを提供することです。 名前空間、クラス、メソッド、またはインターフェイスを検索するには、その完全な、または部分的な名前を API ブラウザー ページに直接入力します。

API ブラウザー

特定のタイプ、メンバー、または名前空間がどの SDK に属しているかわからない場合は、API スコープのドロップダウンで [すべての API] を選択し、利用可能なすべてのリファレンス ドキュメントの中から検索できます。また、検索の範囲を限定する場合は、特定のフレームワークまたは SDK とそのバージョン (たとえば、.NET Framework 4.7) を選択して、その API セット内でのみ検索することができます。

API ブラウザー エクスペリエンスは、.NET ベースの API の目次の上に統合されているため、リファレンス ドキュメント内のどこにいても、API をすばやく見つけることができます。

API ブラウザーに表示されるページ

特定の名前空間に入ると、API ブラウザーは相互に接続されている API のファミリのみにスコープされるため、検索を行うと、常に、コンテキストに基づいて可能な限り最適な結果が返されます。

バージョン管理のサポート

特定のバージョンの .NET Framework または Azure Storage NuGet パッケージで使用可能なメンバーが特定のタイプに存在するかどうかを考える必要がなくなりました。必要なのは API ブラウザー コントロールからバージョンを変更することだけで、コンテンツはそれに応じて調整されます。

リファレンスの目次

オープン ソースを念頭に置いて構築する

API ブラウザーを構築するために、オープンなスタンダードとツールを使用しています。 その中核として、DocFx を利用しています。これには、オープン ドキュメント生成ツールチェーンと、Xamarin の mdoc アプリケーションが含まれます。

すべてのマネージド リファレンス ドキュメントは、NuGet 上で出荷され、.NET Framework や .NET Core などのメイン フレームワーク ディストリビューションの一部となっているバイナリから自動的に出荷されるようになりました。

継続的インテグレーション インフラストラクチャにより、私たちはリリースから数時間以内に公開可能になる最新の API について正確なドキュメントを提供し、投稿ができるようにすることができます。 また、すべての .NET API ドキュメントを ECMAXML 形式で標準化しました。これにより、ドキュメント化されている SDK に関係なく、一貫性のある包括的な API 表現が作成されます。 さらに、自動生成されたドキュメントに埋め込まれた Markdown でコンテンツを提供できるため、ファイル形式の複雑さを把握する必要はありません。リファレンス ドキュメントのコミュニティへの投稿は、来月中に有効になります。

コンテンツにフォーカスする

新しいエクスペリエンスに加えて、リファレンス コンテンツを最適化して、より見つけやすく、読みやすくしました。 常に名前空間に焦点が当てられるように目次を更新しました。 名前空間、型、メンバーに関する情報を参照する場合でも、それぞれのグループ化されたメンバー & すべての子型を持つ親名前空間だけが常に表示されます。

リファレンスの目次

つまり、リファレンス ページが整理され、一般的な概要や例など、最も重要な情報がすべて一目でわかるように表示されます。

また、選択したプログラミング言語に合わせてフィルター処理されるので、最初から自分に関連する例も表示されます。ページの一番下までスクロールしなくても、それらを見つけることができます。

フィードバック駆動型

これは、リファレンス ドキュメントのエクスペリエンスを刷新するためのほんの始まりにすぎません。 ドキュメントをより魅力的で便利なものにし、できるだけ早くご利用いただけるようにするための方法について、フィードバックをお寄せください。 UserVoice サイトにアクセスし、API ブラウザー エクスペリエンスを改良する方法についてご意見をお寄せください。 更新情報をすぐに取得したい場合は、Twitter (@docsmsft) から連絡することもできます。