このページは、github.comに登録されているnsTelemetryのREADME.mdを日本語化したものです。英語版は、github.comを参照してください。
このページの内容は、nsTelemetry 2.2.1 相当の内容が翻訳されています。
NishySoftware.Telemetry.ApplicationInsights
Development status
About
このライブラリーはPCアプリの使用状況や例外の発生状況を計測するためのテレメトリー情報を送信する機能をPCアプリに提供します。
このライブラリーのテレメトリー情報の送信先は、Azure Application Insightとなります。PCアプリから使いやすいようにApplicationInsightsのAPIをラップしたライブラリーとなります。PCアプリは、WindowsおよびLinuxを想定しています。
インストール方法 (Installation)
NuGetパッケージをインストールします。
PM> Install-Package NishySoftware.Telemetry.ApplicationInsights- NishySoftware.Telemetry – nsTelemetry コア ライブラリー
- NishySoftware.Telemetry.ApplicationInsights – nsTelemetry ApplicationInsights ライブラリー
使い方 (How to use)
nsTelemetry (NishySoftware.Telemetry.ApplicationInsights)
このライブラリーは、静的TelemetryクラスとITelemetryインターフェースを提供します。Telemetryクラスのすべての公開メソッドは、静的メソッドとして公開されます。Telemetryクラスは、全体的な設定とITelemetryインターフェースのインスタンスの作成ができます。ITelemetryインターフェース は、テレメトリーデータの設定とテレメトリーの送信ができます。
準備 (Prepare)
- AzureポータルからInstrumentationKeyを取得します
- まだAzureアカウントを持っていない場合は、Azureポータルにアクセスして、アクティブなサブスクリプションを持つアカウントを作成してください。 無料でアカウントを作成
- Azure ポータルで Application Insight リソースを作成します。詳しくは、マイクロソフト社のサイトをご参照ください。
- 新しく作成したリソースページの「概要」ペインに表示されているInstrumentationKeyを取得します。
- このnugetライブラリ(
NisySoftware.Telemetry.ApplicationInsights)を対象とするアプリのプロジェクトにインストールします。 - プロジェクトをビルドすると、
ApplicationInsights.configファイルがプロジェクトに追加されます。 ApplicationInsights.configファイルのInstrumentationKeyタグの内容に、Azureポータルで取得したInstrumentationKeyを設定します。ApplicationInsights.configファイルにInstrumentationKeyを設定したくない場合は、ソースコード内で指定することもできます。
実装 (Implementation)
- 必要に応じてグローバル 共通 テレメトリー データ (プロパティ/メトリック)を設定します。
ApplicationInsights.configファイルにInstrumentationKeyを設定していない場合は、SetInstrumentationKey()を使用してInstrumentationKeyを設定します。- ITelemetryのインスタンスを作成します。
- 必要に応じてグローバル カスタム テレメトリー データ（プロパテ）を設定します。
- 必要に応じてEnableDeveloperMode()でDeveloperModeを設定します。
- ITelemetryインターフェースのTrackEvent() / TrackPageView() / TrackException()メソッドを使用してテレメトリーを送信します。
Example
namespace nsTelemetryAI.Sample
{
using NishySoftware.Telemetry;
using System;
using System.Threading;
using System.Threading.Tasks;
class Program
{
#region Fields
DateTime _startupDateTime = DateTime.UtcNow;
bool _sentEventExit = false;
#endregion Fields
#region Properties
#region Telemetry
static ITelemetry _telemetry;
public static ITelemetry Telemetry
{
get
{
return LazyInitializer.EnsureInitialized<ITelemetry>(ref _telemetry, () =>
{
// [ja] TelemetryDataFlags は、初回は時間がかかるので、非同期で設定する。
Task.Run(() =>
{
// [ja] 共通グローバルプロパティをセットアップする
NishySoftware.Telemetry.ApplicationInsights.Telemetry.CommonDataKinds = TelemetryDataKinds.All;
});
// [ja] ApplicationInsights.configファイルにInstrumentationKeyを配置していない場合は、SetInstrumentationKey()を使用してInstrumentationKeyを設定します。
// NishySoftware.Telemetry.ApplicationInsights.Telemetry.SetInstrumentationKey("your InstrumentationKey");
// [ja] テレメトリーインターフェースのインスタンスを作成する
var telemetry = NishySoftware.Telemetry.ApplicationInsights.Telemetry.CreateTelemetry();
// [ja] 必要ならカスタムグローバルプロパティを追加する
var userDomainName = Environment.UserDomainName;
lock (telemetry.GlobalSyncObject)
{
var prop = telemetry.GlobalProperties;
if (!prop.ContainsKey("UserDomainName"))
{
prop.Add("UserDomainName", userDomainName);
}
}
// [ja] デバッガーがアタッチされているとき、開発者モードの既定値はtrueです。
// デバッガーがアタッチされていないとき、開発者モードの既定値はfalseです。
// 開発者モードがtrueのとき、送信モードの既定値は同期送信です。
// 開発者モードがfalseのとき、送信モードの既定値は非同期送信です。
// 短時間でプロセスが終了するようなコンソールアプリでは、非同期通信を使うとアプリの終了時までに送信しきれないため、trueを推奨します。
#if DEBUG
// [ja] 必要なら、デバッグ版のときに、非同期送信を利用する
NishySoftware.Telemetry.ApplicationInsights.Telemetry.EnableDeveloperMode(false);
// [ja] 必要なら、デバッグ版のときに、常に非同期送信を利用する
//NishySoftware.Telemetry.ApplicationInsights.Telemetry.EnableDeveloperMode(false);
#endif
#if !DEBUG
// [ja] 必要なら、リリース版のときに、常に同期送信を利用する。
NishySoftware.Telemetry.ApplicationInsights.Telemetry.EnableDeveloperMode(true);
#endif
return telemetry;
});
}
}
#endregion
#endregion Properties
#region Methods
void TrackEventStartup(string[] startupArgs)
{
_startupDateTime = DateTime.UtcNow;
Telemetry.TrackEvent("App_" + "General" + "Startup",
"Command", startupArgs.Length > 0 ? startupArgs[0] : null);
}
void TrackEventExit(int exitCode)
{
if (!this._sentEventExit)
{
this._sentEventExit = true;
var exitDateTime = DateTime.UtcNow;
double duration = (exitDateTime - _startupDateTime).TotalSeconds;
Telemetry.TrackEvent("App_" + "General" + "Exit",
"Duration", duration,
"ExitCode", exitCode.ToString());
Telemetry.Flush();
// [ja] Telemetry.Flush()を呼び出した後は少し待ちます。
Thread.Sleep(1000);
}
}
#endregion Methods
static void Main(string[] args)
{
var program = new Program();
program.TrackEventStartup(args);
Console.WriteLine("Hello World!");
program.TrackEventExit(Environment.ExitCode);
}
}
}nsTelemetry API リファレンス
nsTelemetryAI のAPIリファレンスはnsTelemetry.md ファイルとnsTelemetryAI.md ファイルにあります。
このnsTelemetry.mdとnsTelemetryAI.mdは、英語と日本語が併記なため、github.comのファイルを参照してください。
名前空間 : NishySoftware.Telemetry
- ITelemetry インターフェース
- TelemetryDataKinds 列挙型
- TriggerType 列挙型
名前空間 : NishySoftware.Telemetry.ApplicationInsights
- Telemetry クラス
構成ファイル (ApplicationInsights.config)
nsTelemetryは構成ファイルとしてApplicationInsights.configファイルを使用します。
ApplicationInsights.config ファイルの仕様はオリジナルの仕様(英語) から少し拡張されています。
InstrumentationDevKeyタグ
このタグは、開発時に使用することを目的としています。このタグの値は、開発者モードまたはプロセスにデバッガがアタッチされているときに、InstrumentationKeyタグの値の代わりに使用されます。- Windows以外の環境でのServerTelemetryChannelの
StorageFolderプロパティ
ServerTelemetryChannelをWindows以外の環境で使用する場合、ApplicationInsights.configファイルにStorageFolderプロパティ(英語)を明示的に指定する必要があります。
本ライブラリを使用する場合は、StorageFolderプロパティを明示的に指定する必要はありません。StorageFolderプロパティが指定されていない場合は、本ライブラリの適切な値が設定されます。
ライセンス (License)
このライブラリーは、Apache License Version 2.0 で提供されいます。