ぷろじぇくと、みすじら。

DocFX - .NET向けAPIドキュメントを生成するツール

Created at: | Tag: NETFx DocFX

誰も触れていなくて紹介しようと思いつつすっかり忘れていたのですがMarkdownGenerator - C#におけるAPI Reference生成のためのドキュメントツールを見て思い出したのでご紹介です。

DocFXとは

DocFXTools for building and publishing API documentation for .NET projectsGitHubのリポジトリの説明がある通り、 主に.NETプロジェクト向けのAPIドキュメント生成ツールで、GitHubの.NET Foundation Organizationの下でMicrosoftが開発しています。

昔であればSandCastleなどがありましたが、モダンなツールらしくメタデータやMarkdownなどからHTMLのサイトを生成します。

DocFXのサンプル

試しに、MraaSharpからMraaSharpのドキュメントを生成してみました。 設定やページは若干適当ですが雰囲気は感じていただけると思います。

DocFXができること

DocFXができることには以下のようなものがあります。

JekyllやHugoなどの静的サイトジェネレーターに近いですが、 そこまで自由なサイトではなく、ドキュメント生成に重きを置いている印象です。

プレビュー中に変更できなかったり、GitHub上のソースコードへ飛べるなどが最初から準備されているのはその辺の考えがあるのではないでしょうか。

DocFXを使って空のサイトを作る

何はともあれDocFXは使ってみるのが一番です。

利用方法はGetting Started with DocFXを見るとコマンドライン、NuGet、ソースからビルド、Visual Studio…といったいろいろな手段があるのですが、 てっとり早く試すのであればコマンドラインがおすすめです。

まずはDocFXのサイトからビルド済みの最新版をダウンロードします。ダウンロード後にアーカイブを展開すると docfx.exe が含まれているのが確認できると思います。

次にコマンドプロンプトを開いて下記のコマンドを実行してプロジェクトを作成します。

docfx init -q -o SampleDoc
Created folder C:\Users\Tomoyo\Downloads\docfx\SampleDoc\src
(略)
Created File C:\Users\Tomoyo\Downloads\docfx\SampleDoc\api\.gitignore
Created config file C:\Users\Tomoyo\Downloads\docfx\SampleDoc\docfx.json
Successfully generated default docfx project to C:\Users\Tomoyo\Downloads\docfx\SampleDoc
Please run:
        docfx "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\docfx.json" --serve
To generate a default docfx website.
Info: Completed executing in 221.5922 milliseconds.

SampleDoc フォルダが作成されてプロジェクトの初期ファイルも生成されます。 -q オプションを外すと設定項目を一つひとつ入力できます。

サイトをビルドする

プロジェクトを作成したらサイトのHTMLを生成してみます。生成するにはSampleDoc フォルダに移動して次のコマンドを実行してください。

..\docfx build

実行すると _site フォルダにHTMLファイルが生成されます。インターネットに公開する場合にはこの _site 以下を何らかの方法でデプロイするとよいでしょう。

サイトを立ち上げてブラウザで表示してみる

ファイルが生成できたら確認のためにプレビューサーバーを起動してみましょう。

..\docfx --serve
Info: Config file docfx.json found, start generating metadata...
Info: No files are found with glob pattern src/**.csproj, excluding **/obj/**,**/bin/**,_site/**, under directory "C:\Users\Tomoyo\Downloads\docfx\SampleDoc"
(略)
Info: [Apply Theme]Theme is applied.
Serving "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\_site" on http://localhost:8080

これで http://localhost:8080/ でサイトが立ち上がります。 ちなみにデフォルトのポート 8080 を利用中の場合には -p オプションを付けて実行することでポートを指定するとよいでしょう。

..\docfx -p 37564 --serve
(略)
Serving "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\_site" on http://localhost:37564

サイトの停止はCtrl+Cです。なお実際はこのコマンドは build も兼ねています。

C#のプロジェクトからソースコードを生成してみる

さて、次はC#のプロジェクトからAPIドキュメントを生成してみます。ドキュメントを生成したいプロジェクトの一式を何か用意しておいてください。

本当はC#のプロジェクトとDocFXのプロジェクトは近い場所に置いておく方がいいと思うのですが、今回は全然違う場所にあるものを指定します。簡単ですので。

docfx.json が設定ファイルとなっているので、このファイルを開いてmetadata の src の場所に "cwd" としてC#のプロジェクトのフォルダパスを指定します(ここでは "C:\Users\Tomoyo\Documents\Work\GitWork\MraaSharp" を指定しています)。

{
  "metadata": [
    {
      "src": [
        {
          "cwd": "C:\\Users\\Tomoyo\\Documents\\Work\\GitWork\\MraaSharp",
          "files": [
            "src/**.csproj"
          ],

そして再度 docfx コマンドでプレビューサーバーを立ち上げると、自動的にC#のコードを解析してXMLドキュメントコメントを読み込み、HTMLを生成します(正確には一旦メタデータファイルを作る)。

プレビューサーバーが立ち上がったのちサイトにアクセスするとナビゲーションに"Api Documentation"が増え、APIのドキュメントにアクセスできます。

Markdownのページを追加してみる

ところでAPIからの生成以外に普通のWebページを追加することもできますので追加してみましょう。ページはMarkdownなどで書けるようになっています。

ページを追加するにはページの内容を書いたMarkdownファイルを作成し、各フォルダ階層に存在する目次ファイルである toc.yml に追記します。

まずはデフォルトで作られる articles フォルダに hello.md ファイルを作成してみましょう。

# Hello!
コンニチハ!

Markdownファイルを作ったら次は toc.yml に追記です。初期状態では intro.md があるのでその後ろに同じようにnameとhrefのセットを足します。

- name: Introduction
  href: intro.md
- name: Hello!
  href: hello.md

そしてまたdotfxコマンドでプレビューサーバーを起動して生成します。生成すると /articles/ 以下に追加したページが並んで表示できるのを確認できるはずです。

終わりに

というわけでDocFXを使うことで簡単に綺麗なドキュメントサイトを生成できるようになります。GitHubにライブラリを公開したけどAPIドキュメントどうしよう…というときにGitHub Pagesとセットで使ったりできます。

まだ少ししか触っていませんが結構細かくカスタマイズできるようになっているので色々調べてみたいところです。

まどすた #1 でMicrosoft Edgeの話をしたのとASP.NET CoreをBash on Windowsで起動する話

Created at: | Tag: Edge Event

まどすた #1 ~ //build/ 2016 振り返りというイベントが5月21日にありまして、 Microsoft Edgeのセッションをさせていただきました。

元々Windows Insider MeetupというイベントのLT(15分)の資料を元に、 30分という枠に向けて加筆修正を加えデモを中心としていくつか機能を紹介しました。

特にEdge上でのWindows HelloのデモはWindows Insider Meetupの際にも、 MSの方も初めて見たといっていたので多分日本でデモしたのはそれと今回ぐらいだと思います(エヘン。Edgeで体験できるデモサイトも公開しているので興味のある方はお試しください。

Cutting Edge! - Speaker Deck

ASP.NET CoreをBash on Windowsで起動する

ところでEdgeと関係なく、デモサイトはASP.NET Coreで実装したのですが、折角なのでLinuxで動かしてみよう→ とはいえLinuxでサーバー立ち上げるのめんどくさい…→ここにBash on Windowsがあるじゃろ?ということで"ASP.NET Core for Linux on Bash on Windows"でデモしました(ちなみに使っていたのはbashではなくzshです)。

さすがにそのままでは動かないのですがほどほど簡単に動かせます。動かすための手順はデモの時には触れなかったので少し書いておきます。

まず普通にBash on Windows上で.NET CoreのLinux、Ubuntuでのインストール手順を参考にそのままコピペしてインストールします。

するとdotnetコマンドを実行できるようになりますが、そのままではまだ動作しません。どうも何かのシステムコールでサポートしていないフラグを使っているようです(詳しいことは忘れました)。 そこで以下のコマンドを実行します。

apt-get install execstack # 入ってなければ
execstack -c /usr/share/dotnet/shared/Microsoft.NETCore.App/1.0.0-rc2-3002702/libcoreclr.so

さてこれでdotnetコマンドが動くようになります。試しに dotnet init と dotnet restore 、dotnet run を実行するとちゃんと動くことに驚くかもしれません。

ではASP.NET Coreのアプリケーションも?と思い、dotnet restore と dotnet run を実行するとサーバー(Kestrel)が起動しますが、LISTENはしているものの接続できない状態になります。 ネットワーク周りなのかlibuv周りなのかそのあたりがうまく動作しないようです。

そこで Program.cs を開いて WebHostBuilder で UseKestrel にオプションを渡すよう以下のように修正します。

var host = new WebHostBuilder() 
       .UseKestrel(options => 
       { 
           options.ThreadCount = 1; // この設定を足す
       }) 
       .UseContentRoot(Directory.GetCurrentDirectory()) 
       .UseIISIntegration() 
       .UseStartup<Startup>() 
       .Build();

これで dotnet run を実行するとアプリケーションを起動できます。キセキっぽさがありますけど…。

ちょっと手を加える必要がありますがUbuntu向けのCoreCLR、ASP.NET Coreが動作してしまうというのはかなり驚きです。 手軽にLinux環境を用意して色々なものを実行できるBash on Windowsは現状でもすごいのでもっと実装が良くなってくるのが期待できます。

XamarinでもAndroid TVアプリが作りたい

Created at: | Tag: AndroidTv Xamarin CSharp

XamarinがついにVisual Studioの一部となって、Visual Studio利用者であれば追加コストなしで使えるようになりました。Starterではなくてサイズ制限のないフル機能を使えるのでまともな開発ができます。

Xamarinの良し悪しや意義とかは置いておくとして、Androidアプリの開発ができるということはAndroid TVのアプリも作れるということなのでデバッグ実行するまでの流れを試してみました。SonyのBRAVIA(2015)での手順ですがBRAVIA以外のAndroid TV(Nexus Playerなど)でも大体同じ流れだと思います。

動かすアプリはXamarinのデフォルトテンプレートで出来るもの(ボタンを押すとカウントが増えるもの)をそのまま使うことにします。

テレビ(Android TV)側の設定と接続

まずはテレビ側でデバッグをできるように設定します。と言ってもほぼ普通のAndroidと同じです。

  1. 設定から端末情報→ビルドの項目を連打して開発者向けオプションを有効にする
  2. システム機能設定カテゴリの開発者向けオプション→デバッグ→ADBデバッグを「入」

Get started | Sony Developer Worldにも詳しく書いてあります。

つぎにコンピューターからadbコマンドからテレビに接続します。 なお、adbコマンドはXamarin.Androidとともにインストールされたものは%LOCALAPPDATA%\Android\android-sdk\platform-toolsにあります。

adb kill-server
adb start-server
adb connect <IPアドレス>

この adb connect に指定するIPアドレスはテレビのIPアドレスです。ネットワーク設定あたりから確認できます。

C:\Users\Tomoyo\AppData\Local\Android\android-sdk\platform-tools>adb connect 192.168.1.100
connected to 192.168.1.100:5555

コマンドが成功するとコンピューター側には何も出ませんが、テレビ側にUSBデバッグの許可を求めるダイアログが出るのでOKを押してください。

テレビ側で許可をして adb devices で接続したIPのデバイスが出てくれば完了です。

C:\Users\Tomoyo\AppData\Local\Android\android-sdk\platform-tools>adb devices
List of devices attached
192.168.1.100:5555      device
emulator-5554   device

後はVisual Studioのデバッグ実行ボタンにターゲットとしてテレビが出てくるのでクリックするとテレビにアプリがデプロイされてデバッグ実行されます。なお、初回時は共有ライブラリをインストールするのでちょっと時間がかかります。

スクリーンショット: Visual Studio 2015のツールバーから起動

アプリケーションをAndroid TV対応にする

アプリケーションをテンプレートから作ったままだと、Android TV感のない単なるAndroidアプリになる上にホーム画面にも出てこない状態ですので少々対応が必要です。

スクリーンショット: アプリ画面

まず、Android TVの機能を含むライブラリ(v17 Leanback Library)やテーマを使えるように、Xamarin Components StoreからAndroid Support Library V17 Leanbackをインストールします。このコンポーネントをダウンロードするにはXamarinアカウントが必要です。

ちなみにAPI中でLeanbackという言葉が出てきたらそれはAndroid TV的なものを指しています。

そして次にアクティビティにテーマを設定します。 アプリケーションに一括でAndroid TV向けテーマを適用する場合にはAndroidManifest.xmlのapplication要素にtheme属性を追加します。

<application android:label="App17" android:theme="@style/Theme.Leanback"></application>

もしアクティビティ単位で適用したいのであれば、アクティビティのクラスについているActivityカスタム属性のThemeプロパティを設定します。

[Activity(Label = "App17", MainLauncher = true, Icon = "@drawable/icon", Theme = "@style/Theme.Leanback")]

これでタイトルバーが消えたり、ボタンがフラットになったりと見た目がAndroid TV向けっぽくなります。

スクリーンショット: アプリ画面

次にホームにアプリケーションを起動するアイコンというかタイルというかを表示するためのコードを追加します。Android TV向けのアプリケーションはホームから起動できるということを明示的に設定する必要があり、何も指定しないと表示されません。

設定は起動対象としたいアクティビティ、大抵はActivityカスタム属性のMainLauncherプロパティがtrueになっているアクティビティにIntentFilterカスタム属性を追加します。

[Activity(Label = "App17", MainLauncher = true, Icon = "@drawable/icon")]
[IntentFilter(new[] { Intent.ActionMain }, Categories = new[] { Intent.CategoryLeanbackLauncher })]
public class MainActivity : Activity
{
...
}

IntentFilterでカテゴリがCategoryLeanbackLauncherのActionMainを捕まえられるようにするという感じです。

これでホームにアイコンが出てくるようになります。

スクリーンショット: ホーム

ということで準備はできたのであとは頑張ってアプリを作るだけです。

Visual StudioでF5を押すとテレビにアプリを転送、起動してブレークポイントでブレークできるというのはなかなか面白い体験です。そもそもテレビにadbで接続してshellを叩けるという時点で不思議体験でもあります。

ぜひ皆さま、Android TVを買ってC#で開発しましょうということでたまにはアフィリエイトおいておきますね。

ソニー 地上・BS・110度CSデジタルハイビジョン液晶テレビ BRAVIA X8500C 55V型 KJ-55X8500C

Micorosoft Edge Build 14316 リリース

Created at: | Tag: Edge JavaScript HTML

Windows 10 build 14316のリリースで先日のBuildやEdge Summitで出てきたいろいろなアップデートが入ってきました。

プラットフォームアップデートもいろいろありますが、拡張がパワーアップしたのと、Web Notifications、アクセシビリティーツリービューあたりが気になるところでしょうか。

新しい機能

Webプラットフォーム機能

Web Notifications

Webページから通知を表示できる機能で、Edgeの場合にはWindowsの通知機能と連動することになります。

ページが通知の許可を求める(Notification.requestPermission)と、ページの下の方に確認が出てきます。

スクリーンショット: 通知の許可を求める

許可をした状態でページから通知を発行する(new Notification(...))とWindowsの通知として表示されます。

スクリーンショット: 通知が表示される

もちろんちゃんとAction Centerにも入ります。

スクリーンショット: Action Center内にも通知が表示される

F12: アクセシビリティーツリービュー

F12にアクセシビリティーツリービューというものが増えました。 これはページについているroleやスクリーンリーダーに渡す読み上げテキストをツリー表示できるものです。

ツリービューを開くにはF12のDOM Explorerのカラーピッカーのボタンの横に新しいボタンがあるのでそれを押します。

スクリーンショット: F12のアクセシビリティーツリービューをオンにするボタン

ツリービューを表示すると、どういう名前とロールなのかを一覧でき、選択することでその要素にジャンプできます。

スクリーンショット: F12のアクセシビリティーツリービュー

Micorosoft Edge(プレビュー)の拡張について調べる、デバッグする方法

Created at: | Tag: Edge Chrome Extension JavaScript HTML

Micorosoft Edge(プレビュー)の拡張を作ってみるでは未公開の情報を元にノリと勢いでChrome拡張をEdge拡張にしてみましたが、さっくりとできたわけではなくAPIに関しては当然少し調査してから試しました。

その調査方法兼デバッグ方法についてせっかくなのでメモっておきます。もちろん将来のビルドでは手順が変わる可能性がかなり高いです。

まずはChromeが持っているpermissionをすべて列挙したマニフェストを持つ空の拡張を作ります。JavaScript不要です。

{
    "manifest_version": 2,
    "name": "Dummy Extension",
    "version": "1.0",
    "background": {
        "page": "background.html"
    },
    "permissions": [
        "activeTab",
        "alarms",
        /* 長いので省略 (https://gist.github.com/mayuki/5ae554c8e825f32921c7) */
        "webRequest",
        "webRequestBlocking"
    ]
}

バックグラウンドページはこんな感じでtitle要素だけ。

<!DOCTYPE html>
<!-- 名前は付けておいた方がいい -->
<title>Dummy Extension - BackgroundPage</title>

そしてACLを付けて、

icacls . /grant "*S-1-15-2-3624051433-2125758914-1423191267-1740899205-1073925389-3782572162-737981194":"(OI)(CI)(WDAC,WO,GE)"

Edgeに読み込ませます。

デバッグコンソールを開く

これで拡張は読み込まれましたがEdgeのデバッグする口がありません。Chromeなどでは拡張画面からいろいろ開けるのですがそういうインタフェースは見当たりません。

そこでF12開発者ツールをスタンドアローンで立ち上げます。実は結構前からF12開発者ツールは単体で起動できるようになっています。

単体で起動するにはC:\Windows\SysWOW64\F12にあるF12Chooser.exeを実行します。するとF12開発者ツールをどのインスタンスのEdgeにアタッチするか、という画面が表示されます。

F12Chooser

この画面でさっき作った"Dummy Extension - BackgroundPage"を選択します。すると指定したページ、つまり拡張のバックグラウンドページにアタッチされたF12開発者ツールが起動します。

F12開発者ツールが立ち上がる

そうしたらあとはコンソールでいろいろ試してみます。

windowオブジェクトにbrowserやchromeが生えている

chromeオブジェクトにはほとんど機能がないこと、pageActionの実装が中途半端なこと、webRequest/webNavigationがある(使えたとは言っていない)といったことが分かります。コンテキストメニューを足してみるのもここからできます。

ちなみにこのアタッチする手段を使うことで拡張をデバッグできます。…が、読み込み時のエラーのキャッチはできないのでなかなか厳しいです。そのあたりは将来正式に解放されるときに手段が整うのではないかと思います。