※本記事は、Yan Sunによる”Using Oracle Cloud Infrastructure Software Development Kit for .NET with VS Code or VS Codespaces“を翻訳したものです。

本記事はオラクルの同僚であるNabeel Al-Saberと共同で執筆したものです。

このブログでは、Visual Studio CodeとOracle Cloudの.NET向けソフトウェア開発キット（SDK for .NET）を使用して、Oracle Cloudにアクセス可能なアプリケーションを構築する方法について説明します。Oracle Cloudへのオンボーディングの手順、Oracle Cloud Infrastructure開発者用ツールを使用するために必要となる一般的なセットアップ方法および.NET SDK特有の詳細情報、さらにはこのアプリケーションをVS Codespacesで実行、デバッグする方法についても取り上げたいと思います。

Oracle Cloudの.NET向けソフトウェア開発キット（SDK for .NET）は2020年7月にリリースされました。Oracle Cloudの開発者用ツール・ファミリーに加わるSDK for .NETによって、.NET/C#開発者がOracle Cloudを操作できるようになります。

 

Oracle Cloud無償ティアの提供について

アプリケーションの開発を始める前に、Oracle Cloud Infrastructureアカウントについて簡単にご紹介しましょう。

Oracle Cloudを初めて使用する場合に必要となる最初のステップは、Oracle Cloud Infrastructureアカウントの作成です。オラクルのクラウド・サービスにサインアップして感触をつかむには、Oracle Cloud無償ティアが適しています。

 

Oracle Cloudでの認証のための構成

Oracle Cloud Infrastructure SDK for .NET経由でOracle Cloudを操作する場合には、アクティブなOracle Cloudアカウントで認証する必要があります。このプロセスでは、APIの鍵ペアと、SDKで読み取り可能な構成ファイルを使用します。

Oracle Cloud SDK for .NETは公開されている他のSDKと同様に、PEM形式のRSA鍵ペアを利用して認証します。この鍵ペアと関連情報を生成するには、以下の手順を実行します。

  • Oracle Cloudサービスにアクセスするための適切な権限を持つユーザーを作成します。ユーザー、グループの作成方法と権限の設定方法については、 こちらを参照してください。ユーザーを作成済みの方はこの手順をスキップしてください。

  • まだ入手していない場合は、鍵ペアを生成します。API署名用の鍵の生成方法については、こちらを参照してください。この際に、秘密鍵をパスフレーズで保護することを推奨します。秘密鍵はご自分で厳重に保管し、公開鍵を以下のいずれかの手順でアップロードしてください。

  • 公開鍵のフィンガープリントを取得：その方法については、こちらを参照してください。フィンガープリントはコンソールから容易に取得できます。次の手順で公開鍵をアップロードした後、コンソールにフィンガープリントが表示され、そこからコピーできます。

  • コンソールで公開鍵をユーザー・アカウントにアップロード（まだの場合）：その方法については、こちらを参照してください。

構成ファイルではOracle Cloud SDK for .NETへの情報を指定します。このファイルのデフォルトの場所はホーム・ディレクトリ（~/.oci/config）ですが、他の場所に保存することもできます。構成ファイルには、生成された鍵とフィンガープリントに加えて、テナンシーOCIDとユーザーOCIDを含める必要もあります。これらの一意識別子はコンソールで確認できます。テナンシーOCIDとユーザーOCIDの確認方法については、こちらを参照してください。

以下のサンプルの構成ファイルをお使いの環境にコピーしてご利用ください。その際、自分のユーザー・アカウントに合わせて、このファイル内の値を更新してください。

?
1
2
3
4
5
6
7
[DEFAULT]
user=ocid1.user.oc1..
fingerprint=f7:12:34:56:78:90:ab:bc:cd:de:ef:98:87:65:43:21
key_file=~/.oci/my_oci_api_key.pem
tenancy=ocid1.tenancy.oc1..
region=us-phoenix-1
pass_phrase=SomePassPhrase

 

VS CodespacesでのOCI構成ファイルのアップロード

VS CodespacesのようなオンラインIDEを使用する場合は、アプリケーションの実行時にOracle Cloudのリソースにアクセスできるように、構成ファイルと必要な鍵をアップロードする必要があります。

これらのファイルをリモートIDEにアップロードする方法はいくつかあります。このブログでは、ターミナルから構成ファイルを作成する方法を説明します。

まだ表示されていない場合は、VS Codespaceでターミナルを開きます。メニューを開き、「View」に移動して「Terminal」を選択します。次に、以下の手順を実行します。

?
1
2
3
4
5
6
7
8
9
10
11
# Create a new config file under ~/.oci
mkdir ~/.oci
# Copy the content of the config
vi ~/.oci/config
# Select the correct path for the key file in the config: key_file=~/.oci/oci_api_key.pem
  
# Copy the content of the local oci_api_key.pem file and paste it in the remote file
vi ~/.oci/oci_api_key.pem
  
# Copy the content of the local oci_api_key_public.pem file and paste it in remote file
vi ~/.oci/oci_api_key_public.pem

以下のスクリーンショットに、構成ファイルと鍵ファイルを作成した後のVS CodespacesのTerminalを示します。

A screenshot of the terminal in VS Codespaces.

 

.NET Coreアプリケーションでの作業

C#拡張のインストール

VS CodeのC#サポートはオプションの拡張を通じて利用でき、この拡張はマーケットプレイスからインストールできます。この拡張をインストールするには、左側の「Extensions」アイコンをクリックし、C#を検索します。Microsoft製のこの拡張をインストールします。

A screenshot of the C# extension installation screen in the Marketplace.

C#拡張はOmniSharpによって動作しており、project.jsonやcsprojプロジェクトのサポート、IntelliSenseなどのコード編集サポート、go to定義、構文ハイライト、参照先検索など、C#開発のための多くの便利な機能を提供しています。

 

新規.NET Coreアプリケーションの作成

VS Codeでは利用できない機能の1つに、アプリケーション作成ウィザードがあります。そのため、アプリケーションの作成はVS Codeの外部で実行する必要があります。

.NET Core SDKがインストール済みであれば、.NET Core CLIからプロジェクトを作成できます。

  1. ターミナルを開き、プロジェクトを作成するフォルダに移動します。このフォルダ名は次の手順でプロジェクト名として使用されます。

  2. 以下の.NET Core CLIコマンドを実行すると、完全な機能を備えたプロジェクトが作成されます。

    ?
    1
    dotnet new console

  3. この新規プロジェクトをビルドして実行するには、以下の.NET Core CLIコマンドを実行します。成功した場合は、“Hello World!”と出力されます。

    ?
    1
    dotnet run

VS Codespacesでは、この手順をターミナルで実行することでプロジェクトを作成できます。

 

既存プロジェクトのロード

VS Code

C#拡張をインストールし.NET Coreアプリケーションを作成した状態で、プロジェクトをVS Codeで開くことができます。

  1. Fileメニューから「Open…」を選択します。

  2. C#プロジェクトを格納しているフォルダに移動します。

  3. Openをクリックします。

  4. “Required assets to build and debug are missing.Add them?”という通知が表示された場合は、「Yes」を選択して依存先を自動的にロードします。

これで、プロジェクト構造とソース・コードをVS Codeで確認できるようになりました。その中に.csprojファイルとProgram.csファイルがあるはずです。

VS Codespaces

まず、プロジェクト・ファイルをGitHubにアップロードします。これで、Codespaceを作成して、インポートするプロジェクトのGitHubリンクを指定できるようになります。

 

Oracle Cloud Infrastructure SDK for .NETパッケージのインポート

Oracle Cloud Infrastructure SDK for .NETはNuGetパッケージとして公開されています。このSDKを使用してOracle Cloudを操作するには、NuGetパッケージをインポートする必要があります。VS CodeではC#サポートの場合と同様に、“NuGet Package Manager”という拡張をインストールする必要があります。もう一度Extensionsビューに移動し、“nuget package manager”を検索します。目的の拡張が結果リストの一番上に表示されます。

この拡張をインストールした後、個別のNuGetパッケージを検索してインストールできます。

  1. Viewメニューから、「Command Palette…」を選択します（またはショートカット・キーを使用します）。

  2. ポップアップ内で“nuget”と入力すると、検索結果に“NuGet Package Manager:Add Package”が表示されます。このオプションを選択します。

    A screenshot of 'nuget' typed into the search bar above the expanded options that include nuget.

  3. 次のダイアログ・ボックスで、インポートするパッケージの名前を入力して[Enter]キーを押します。名前の一部（OCI.DotNetSDKなど）を入力してもかまいません。その場合、その一部を含むすべてのパッケージが検索ボックスに表示されます。

    A screenshot of the search results for OCI.DotNetSDK.

  4. インポートするパッケージを選択すると、そのパッケージで見つかったすべてのバージョンが表示されます。使用するパッケージに加えて、OCI.DotNetSDK.Commonパッケージもインポートする必要があります。認証やHTTPリクエストの送信などの重要な機能がすべて含まれているためです。

    A screenshot of the version options for the package.

  5. 使用するバージョン（通常は最新バージョン）を選択すると、そのパッケージがプロジェクトに自動的に追加されます。

この時点でプロジェクト内の.csprojファイルを見ると、ItemGroupセクションに新規のPackageReferenceが含まれています。

このアプリケーションでは、Oracle Cloud SDK for .NETから以下の2つのNuGetパッケージを検索してインポートします。

  • OCI.DotNetSDK.Common

  • OCI.DotNetSDK.Identity

.csprojファイルに以下のようなItemGroupセクションがあるはずです。

?
1
2
3
4
<ItemGroup>
  <PackageReference Include="OCI.DotNetSDK.Common" Version="4.1.0"/>
  <PackageReference Include="OCI.DotNetSDK.Identity" Version="4.1.0"/>
</ItemGroup>

 

初めてのOracle Cloud .NETアプリケーションのコーディング

これで、アプリケーション内でソース・コードを作成してOracle Cloudを操作する準備ができました。Oracle Cloudでのユーザー認証に必要となるすべての情報がすでに構成ファイルに含まれているため、あとはサービス・クライアントがこの構成ファイルを使用するように構成し、そのサービス・クライアントを使用してサービスAPIを呼び出すだけです。自動生成されたProgram.csに以下の変更を加えて更新します。

  1. 正しいusing文がすべて記述されていることを確認します。以下に重要な例を示します。

    • System.Threading.Tasks：非同期メソッドのために使用される

    • Oci.Common.Auth：認証詳細プロバイダを作成するために使用される

    • Oci.<Service>：サービス・クライアントを作成するために使用される

    • Oci.<Service>.Requests、Oci.<Service>.Responses：APIリクエスト・オブジェクトとレスポンス・オブジェクトのために使用される

以下の例ではIdentityServiceが使用されています。

?
1
2
3
4
5
using System.Threading.Tasks;
using Oci.Common.Auth;
using Oci.IdentityService;
using Oci.IdentityService.Requests;
using Oci.IdentityService.Responses;

  • Main関数で、“Hello World!”を出力する文を削除して、構成ファイルの値を使用する認証詳細プロバイダを作成します。構成ファイルを使用して認証詳細を初期化する際の記述方法は複数あります。

    構成ファイルがデフォルトの場所（~/.oci/config）に格納されている場合は、プロファイル名を指定するだけで認証詳細プロバイダを作成できます。

    ?
    1
    var config = new ConfigFileAuthenticationDetailsProvider("DEFAULT");

    構成ファイルがカスタムの場所にある場合は、ファイル・パスも指定する必要があります。

    ?
    1
    var config = new ConfigFileAuthenticationDetailsProvider("/path/to/config/file", "DEFAULT");

  • この認証詳細プロバイダを使用してサービス・クライアントを作成します。

    ?
    1
    2
    3
    using (var client = new IdentityClient(config))
    {
    }

  • リクエスト・オブジェクトを作成し、サービス・クライアントを使用してこのオブジェクトを送信し、サービスから返されるレスポンスを受け取ります。

    ?
    1
    2
    3
    4
    5
    6
    7
    8
    9
    var listCompartmentsRequest = new ListCompartmentsRequest
    {
        CompartmentId = compartmentId
    };
     
    using (var client = new IdentityClient(config))
    {
        ListCompartmentsResponse response = await client.ListCompartments(listCompartmentsRequest);
    }

  • このように非同期関数を呼び出しているため、Main関数を非同期関数にして更新する必要もあります。

    ?
    1
    static async Task Main(string[] args)

最終的なコードは以下のブロックのようになります。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
using System;
using System.Threading.Tasks;
using Oci.Common.Auth;
using Oci.IdentityService;
using Oci.IdentityService.Requests;
using Oci.IdentityService.Responses;
 
namespace oci_sdk_dotnet_blog
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Needs a valid compartment ocid from your tenancy.
            var compartmentId = "ocid1.tenancy.oc1..";
            try
            {
                var config = new ConfigFileAuthenticationDetailsProvider("DEFAULT");
 
                var listCompartmentsRequest = new ListCompartmentsRequest
                {
                    CompartmentId = compartmentId
                };
 
                using (var client = new IdentityClient(config))
                {
                    ListCompartmentsResponse response = await client.ListCompartments(listCompartmentsRequest);
                    Console.WriteLine($"Found {response.Items.Count} compartments.");
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }
        }
    }
}

 

VS Codeでのアプリケーションの実行とデバッグ

これで、アプリケーションの実行やデバッグができるようになりました。これらはVS Code内で実行できます。

 

アプリケーションの実行

デバッグをせずにアプリケーションを実行するには、「Run」メニューに移動し、「Run Without Debugging」を選択します。

このアプリケーションを初めて実行する場合、VS Codeでのこのアプリケーションの構成が正しくない可能性があります。VS Codeが自動的に判断できない場合、実行環境を指定するように求められます。この手順の実行中に環境の指定が求められた場合は、「.NET Core」を選択します。これにより、プロジェクト・ディレクトリの“.vscode”というフォルダ内に2つのファイルが自動的に作成されます。このtasks.jsonとlaunch.jsonという2つのファイルは、VS Codeに対してアプリケーションのビルド方法と実行方法を指示するものです。

A screenshot of the options for selecting an environment where VS Codespaces creates the tasks.json and launch.json files.

tasks.jsonファイルとlaunch.jsonファイルが作成された後にプロジェクトを再実行すると、VS Codeウィンドウの下側のデバッグ・コンソールにログが表示されます。正常に実行された場合、このプロジェクトのビルドが完了し、以下のような出力が表示されます。

-------------------------------------------------------------------
You may only use the Microsoft .NET Core Debugger (vsdbg) with
/
Visual Studio Code, Visual Studio, or Visual Studio for Mac software

to help you develop and test your applications.
-------------------------------------------------------------------

Found 40 compartments.

 

アプリケーションのデバッグ

他のIDEを使用してコードをデバッグする場合と同様に、行番号の左側をクリックすることでコード内にブレークポイントを設定できます。

デバッグを開始するには、「Run」メニューに移動し、「Start Debugging」を選択します。先ほどと同様に、VS Codeでプログラムの実行やデバッグが構成されていない場合は、アプリケーションの実行に関する前述の手順に従って、tasks.jsonファイルとlaunch.jsonファイルを作成します。デバッグ・セッションを開始した後は、進行状況を監視し、設定したブレークポイントで停止できます。VS Codeウィンドウの左側でRunアイコンをクリックして実行ビューまたはデバッグ・ビューに移動します。このビューで、コール・スタック、変数など、すべてのIDEに共通する情報を確認できます。

A screenshot of the debugging function in the Run section.

VS Codeウィンドウの右上にはフローティング・コントロールが表示されています。このコントロールを使用して、ステップ・オーバー、ステップ・イン、ステップ・アウト、再開、停止などの一般的なデバッグ操作を実行できます。

A screenshot of the floating control in the VS Code window.

 

ロギング

ロギングはプログラムの重要なデバッグ手法であり、Oracle Cloud Infrastructure SDK for .NETではロギングのためにNLogが使用されます。このSDKを使用するすべてのアプリケーションでSDKからのログを取得できますが、そのためにはプロジェクトに独自のNLog構成ファイルを配置する必要があります。この構成ファイルに、ロギングのターゲットと、希望するロギング・レベルを定義します。

以下のサンプルの構成ファイルでは、NLogに対して、コンソールとファイルの両方にロギングするように指示しています。コンソール出力では、Infoロギング・レベル以上のメッセージが出力されます。ログ・ファイルには、Debugロギング・レベル以上のすべての情報が記録されます。ロギング・レベルの詳細については、NLogの公式ドキュメントを参照してください。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <targets>
        <target name="console" xsi:type="ColoredConsole" />
        <target name="file" xsi:type="File" fileName="${CurrentDir}/logs/${date:format=yyyy-MM-dd}.log" />
    <code></targets>
    <rules>
        <logger name="*" minlevel="Info" writeTo="console" />
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>
</code>

SDKからのログを参照するには、NLog.configファイルを作成して、プロジェクトのルートに追加します。さらに、.csprojファイルに以下のセクションを追加して、このファイルを更新します。

?
1
2
3
4
5
<ItemGroup>
  <Content Include="NLog.config">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </Content>
</ItemGroup>

プログラムを実行するかデバッグしてみましょう。通常のコンソールへのロギングに加えて、“logs”というフォルダ（NLog.configで定義されています）がプロジェクトに追加されました。このフォルダにログ・ファイルが格納され、タイムスタンプがそのファイル名に付けられます（ファイル名についてもNLog.configで定義されています）。コンソール出力とログ・ファイルの両方に、以前にはなかった情報が含まれています。それらのロギングの行はOracle Cloud SDK for .NETからのものです。

NLog.configをプロジェクトに追加することで確認できるのはOracle Cloud SDK for .NETからのロギングだけですが、NLogを使用してアプリケーションからの情報もロギングできます。その場合に必要となる変更は、クラスに以下のロガーを追加することだけです。

?
1
private static NLog.Logger logger = NLog.LogManager.GetCurrentClassLogger();

さらに、コンソールに書き込まれていたすべての文を、以下のようなログ出力メソッドに書き換えることもできます。

?
1
logger.Info($"Found {response.Items.Count} compartments.");

 

ユーザー値の指定

先ほどの例では、ListCompartmentRequestオブジェクトから要求される“CompartmentId”の値を明示的に設定しました。この値をソース・コードから隠したい場合や、他の開発者が値をカスタマイズできるようにしたい場合は、以下のいずれかの方法で、情報をアプリケーションに提供するようにしてください。

 

環境変数からの読取り

VS Codeでは、すべてのターミナル・セッションで利用可能な環境変数（たとえば、MacOSやLinuxで.bash_profileにより設定された環境変数）にアクセスできます。または、launch.jsonファイルに“env”セクションを追加して、VS Code内で特定のアプリケーション用に環境変数を定義することもできます。launch.jsonファイルの生成方法については、“VS Codeでのアプリケーションの実行とデバッグ”セクションを参照してください。

ここでは例として、このアプリケーションの実行やデバッグの際に使用する環境変数“VSCODE_COMPARTMENT_ID”を追加します。

A screenshot of the .NET Core Launch (console) with the added VSCODE_COMPARTMENT_ID variable.

これで、compartmentId変数に値をハードコードする代わりに、以下の環境変数から値を取得できます。

?
1
var compartmentId = Environment.GetEnvironmentVariable("VSCODE_COMPARTMENT_ID");

環境変数をlaunch.jsonファイル内で設定する場合、ターミナル（VS Code内のターミナルを含む）からアプリケーションを実行すると、この環境変数にアクセスできません。アプリケーションがこの値を環境変数として読み取ることができるのは、VS Codeでアプリケーションを起動する場合に限られます。

 

構成ファイルからの読取り

構成ファイル経由でアプリケーションに対して値を提供することもできます。これまでは、このファイルにユーザー認証情報を指定していましたが、キーと値のペアの形式で他のデータも指定できます。Oracle Cloud SDK for .NETでは、構成から値を読み取るための関数が用意されています。既存の構成ファイルのデフォルト・プロファイルの後ろに、さらにキーと値のペアを追加してみましょう。

?
1
2
3
4
5
6
7
8
[DEFAULT]
user=ocid1.user.oc1..
fingerprint=f7:12:34:56:78:90:ab:bc:cd:de:ef:98:87:65:43:21
key_file=~/.oci/my_oci_api_key.pem
tenancy=ocid1.tenancy.oc1..
region=us-phoenix-1
pass_phrase=SomePassPhrase
config_compartment_id=ocid1.tenancy.oc1..

次に、キー“config_compartment_id”を使用して構成ファイルから値を読み取るようにコードを更新できます。ConfigFileReaderにアクセスするには、“using Oci.Common;”を追加します。

?
1
2
var config = ConfigFileReader.Parse(ConfigFileReader.DEFAULT_FILE_PATH);
var compartmentId = config.GetValue("config_compartment_id");

まとめ

このブログでは、Oracle Cloud Infrastructure SDK for .NETを使用する.NET CoreアプリケーションをVS Codeで作成、構成、実行またはデバッグするエンド・ツー・エンドのサンプルを段階的に確認しました。多数のIDEが存在する中で、VS Codeにも独自の長所と制約があります。C#開発用に構成した後のVS Codeは、Oracle Cloud SDK for .NET NuGetパッケージの閲覧、検索、インポート、ソース・コード編集、アプリケーションの実行やデバッグの機能を利用して、.NET Coreアプリケーションを簡単に開発できます。

Oracle Cloudに関心のある.NET開発者の方には、このSDKを通じてOracle Cloudを試した上で、オラクルが無償ティア・プログラム経由で提供している優れたサービスを活用されることを強く推奨します。Oracle Cloudを操作するアプリケーションを初めて開発する皆さまのためにこのブログがお役に立つことを願っております。ご質問やご意見がありましたら、コメントをお送りください。