こんにちは、Visual Studio サポートチームのオオカワです。 書き溜めていながらも、公開できていなかった記事を今週は一挙公開していこうかと思います！
今回は、Web サービスと通信するような ClickOnce アプリケーションの実装で、しばしば起こる運用についてまとめてみました。
以下のような ClickOnce アプリケーション開発のシナリオを仮定します。
・テスト用サーバーと、本番用サーバーで、Web サービスのエンドポイント URL が異なるため、アプリケーション設定ファイル (app.config) でエンドポイントの切り替えを行う ・テストに使ったバイナリ一式をそのまま本番用サーバーで利用したい（再発行は行いたくない）
アプリケーション設定ファイルに記載されたエンドポイントの URL を書き換えたあと、以下のエラーが発生してアプリケーションが起動できない。
エラーの詳細 この操作中に次のエラーが検出されました。 * [2011/04/07 22:25:42] System.Deployment.Application.InvalidDeploymentException (HashValidation) - ファイル SampleApp.exe.config は、マニフェストで指定されているものとは異なる処理されたハッシュを持っています。
アプリケーション マニフェストには、アプリケーション設定ファイルのハッシュ値ならびにサイズが含まれています。 一方、エンドポイント URL の変更により、アプリケーション設定ファイルのハッシュ値ならびにサイズは変わります。 ここで、マニフェストの情報とファイルの実体の情報の不整合が生じ、これを ClickOnce ローダーが検出することでアプリケーションの起動がブロックされます。
アプリケーション マニフェストに含まれる、アプリケーシ��ン設定ファイルのハッシュ値ならびにサイズを、手動で明示的に更新する必要があります。 但し、アプリケーション マニフェストは通常署名されておりますので、更新後にはさらに再署名を行う必要があります。 そのためには、弊社 SDK ツールに含まれる、mage.exe ならびに mageui.exe を利用します。
mage.exe の利用方法についてはこちらをご覧ください。 http://msdn.microsoft.com/ja-jp/library/acz3y3te.aspx
mageui.exe の利用方法についてはこちらをご覧ください。 http://msdn.microsoft.com/ja-jp/library/xhctdw55.aspx
以下に、まず mage.exe のコマンドラインオプションについてご説明し、その後実践編として、ビルドしたマスターのバイナリを、テスト用と本番用の設定に振り分ける作業をコマンドラインから行うためのチュートリアルを記載いたします。
Mage.exe のコマンドライン オプションを以下にまとめましたので併せてご参考下さい。
アプリケーション マニフェスト更新用コマンドライン オプション ==== -Update <アプリケーションマニフェストへのパス> : 引数に指定したアプリケーションマニフェストを更新します。今回はベースとなるマニフェストを更新するので本オプションを指定します。 -FromDirectory <アプリケーション マニフェスト の存在するディレクトリ> : 本オプションの引数に指定したディレクトリ配下のファイルが更新後のアプリケーション マニフェストに含まれます。 ※不要なファイルが指定ディレクトリに存在すると、そのファイルまで ClickOnce の発行対象になります。不要なファイルについては予め削除してください。 -Version <バージョン番号> : 実際に発行時に指定するバージョン番号を "N.N.N.N" という形で記述します。(N は 32 bit 符号なし整数です) -Name <アプリケーション名> : アプリケーション名として指定したい文字列を指定します。 -CertFile <証明書ファイルへのパス> : アプリケーションに署名するための証明書ファイルへのパスを記述します。 -Password <証明書ファイルのパスワード> : 証明書を利用するためのパスワードを指定します。 -ToFile <マニフェストファイルの出力先> : 本引数には、更新後のアプリケーション マニフェストの出力パスを指定します。指定しなかった場合、入力ファイルが上書きされます。
配置マニフェスト更新用コマンドライン オプション ==== -Update <配置マニフェストへのパス> : 引数に指定したアプリケーションマニフェストを更新します。 -AppManifest <アプリケーション マニフェストへのパス> : 更新したアプリケーションマニフェストへの相対パスを指定します。 -ProviderUrl <発行先 URL> : 配置マニフェストの実際の発行先 URL をフルパスで指定します。 -AppCodeBase <発行先 URL> : アプリケーション マニフェストの実際の発行先 URL をフルパスで指定します。 -Version <バージョン番号> : 実際に発行時に指定するバージョン番号を "N.N.N.N" という形で記述します。(N は 32 bit 符号なし整数です) -MinVersion <バージョン番号> : アプリケーションの起動を許可する、最低限のバージョン番号をここに記述します。常に最新版を利用するように設定するためには、Version オプションに指定したものと同一の値を指定します。 -Name <アプリケーション名> : アプリケーション名として指定したい文字列を指定します。 -CertFile <証明書ファイルへのパス> : アプリケーションに署名するための証明書ファイルへのパスを記述いたします。 -Password <証明書ファイルのパスワード> : 証明書を利用するためのパスワードを指定します。
また、mage ツールを利用して、ClickOnce アプリケーションを手動で配置する手順については、以下の技術情報もご参照ください。
チュートリアル : ClickOnce アプリケーションを手動で配置する http://msdn.microsoft.com/ja-jp/library/xc3tc5xx.aspx
- 今回のチュートリアルのフォルダ構成 C:\work ディレクトリ配下に以下のディレクトリ構成で発行作業を行います。 C:\work\Sample1\Sample1 : プロジェクト ファイル (*.csproj の格納先) C:\Master : マスターとなる ClickOnce アプリケーションの発行先 C:\publish : アプリケーションのそれぞれの発行先 (テスト環境を "test"、本番環境を "main" と仮定) C:\config : 環境毎に設定を行ったコンフィグファイルの格納先
以後の作業は C:\work ディレクトリをカレントディレクトリとしてコマンドを記述しております。 まずは、検証用にフォームのみを表示するようなサンプルのソリューション (Sample1) を C:\work ディレクトリ配下に作成いただきまして手順をご確認ください。
- 手順 (1) msbuild でマスターの ClickOnce アプリケーションを発行します。 ・コマンド例 > msbuild C:\work\Sample1\Sample1\Sample1.csproj /t:publish /p:configuration=Release /p:publishdir=..\..\Master
(2) マスターの ClickOnce アプリケーションのフォルダ名を変更します。 ※この後の手順説明の簡略化の為、便宜的に行っております。必須の手順ではありません。
・コマンド例 > rename "c:\work\Master\Application Files\Sample1_1_0_0_0" Sample1
(3) マスターファイルを、各環境毎の出力先へコピーします。 ・コマンド例 > xcopy Master "publish\test\" /S /Y > xcopy Master "publish\main\" /S /Y
※ほかにも発行先を作る必要があれば、適宜 xcopy コマンドを実行します。
(4) 環境毎の app.config ファイルをコピーします。 ・コマンド例 > copy "config\test.app.config" "publish\test\Application Files\Sample1\Sample1.exe.config.deploy" /Y ※上記コマンドを、環境数分繰り返します。
(5) 発行先に含まれるファイルの deploy 拡張子を一旦外します。 ・コマンド例 > rename "publish\test\Application Files\Sample1\Sample1.exe.config.deploy" Sample1.exe.config > rename "publish\test\Application Files\Sample1\Sample1.exe.deploy" Sample1.exe ※上記コマンドを、環境数分繰り返します。また、上記以外の *.deploy ファイルがある場合、そのファイルについても同様のコマンドでリネームします。
これは、今後の mage.exe を用いた作業が deploy 拡張子に非対応の為の処理でございます。
(6) アプリケーション マニフェストを更新します。 ・コマンド例 > mage -Update "publish\test\Application Files\Sample1\Sample1.exe.manifest" -fd "publish\test\Application Files\Sample1" -Version <AppVer> -Name <AppName> -ToFile "publish\test\Application Files\Sample1\Sample1.exe.manifest" ※ <AppVer> には、任意のバージョン番号を指定します。バッチファイルを作る際には、変数に事前にバージョンを格納しておくと便利です。 ※ <AppName> には、任意のアプリケーション名を指定します。 ※ 上記コマンドを、環境数分繰り返します。
アプリケーションマニフェスト中の config ファイルの再読み込み、バージョン番号、アプリケーション名の更新を行います。 なお、コマンドラインオプションについての解説は、手順を全てお伝えし終わった後に補足としてまとめさせていただきます。
(7) アプリケーション マニフェストを再署名します ・コマンド例 > mage -Update "publish\test\Application Files\Sample1\Sample1.exe.manifest" -CertFile "Sample1\Sample1\Sample1_TemporaryKey.pfx" -Password password ※上記コマンドを、環境数分繰り返します。
(8) 配置マニフェストを更新します。 ・コマンド例 > mage -Update "publish\test\Sample1.application" -AppManifest "publish\test\Application Files\Sample1\Sample1.exe.manifest" -ProviderUrl "http://servername/publish/test/Sample1.application" -AppCodeBase "http://servername/publish/test/Application Files/Sample1/Sample1.exe.manifest" -Version <AppVer> -MinVersion <AppVer> -Name <AppName> ※上記コマンドを、環境数分繰り返します。
配置マニフェスト中の、発行先ならびに更新先、アプリケーション名、バージョン番号、更新必須の設定を行います。
(9) 配置マニフェストを再署名します。 > mage -Update "publish\test\Sample1.application" -CertFile "Sample1\Sample1\Sample1_TemporaryKey.pfx" ※上記コマンドを、環境数分繰り返します。
(10) deploy 拡張子を元に戻します。 ・コマンド例 > rename "publish\test\Application Files\Sample1\Sample1.exe.config" Sample1.exe.config.deploy > rename "publish\test\Application Files\Sample1\Sample1.exe" Sample1.exe.deploy ※上記コマンドを、環境数分繰り返します。また、上記以外に (5) のステップでリネームしたファイルがある場合、そのファイルについても同様のコマンドで deploy 拡張子を戻します。
(11) http://servername/publish 以下に、一連の作業で作成した publish ディレクトリ配下を全てコピーします。
ClickOnce をご利用いただいているお客様のお役に立てれば幸いです。 何かご不明点があれば、是非弊社サポートサービスまでお問い合わせいただければ、弊社エンジニアが責任を持ってお困りごと解決のお手伝いをさせていただきます。
サポート チームとして実際にお問い合わせをいただいた案件を参考に、多くの方にご活用いただけそうな情報をここでまとまった形で発信し、一人でも多くの方のお役に立てればと思っております。
今後ともどうぞよろしくお願いします。
==== Visual Studio サポート チーム オオカワ ====