EWS マネージ API クライアント アプリケーションの概要Get started with EWS Managed API client applications

EWS マネージ API を使用して、Exchange 用の単純な Hello World メール クライアント アプリケーションを開発します。Develop a simple Hello World email client application for Exchange by using the EWS Managed API.

EWS マネージ API では、クライアント アプリケーション、ポータル アプリケーション、サービス アプリケーションから Web サービス メッセージを送受信するための、直観的で使いやすいオブジェクト モデルが用意されています。EWS マネージ API を使用して、Exchange Online、Office 365 の一部としての Exchange Online、Exchange サーバー メールボックスに格納されているほとんどすべての情報にアクセスすることができます。この記事にある情報は、初めて EWS マネージ API のクライアント アプリケーションを開発する場合に役立ちます。The EWS Managed API provides an intuitive, easy-to-use object model for sending and receiving web service messages from client applications, portal applications, and service applications. You can access almost all the information stored in an Exchange Online, Exchange Online as part of Office 365, or an Exchange server mailbox by using the EWS Managed API. You can use the information in this article to help you develop your first EWS Managed API client application.

注意

EWS マネージ API は、GitHub でオープンソース プロジェクトとして利用可能になりました。The EWS Managed API is now available as an open source project on GitHub http://aka.ms/ews-managed-api-github . You can use the open source library to: オープン ソース ライブラリを使用して、以下のことができます。You can use the open source library to:

  • バグ修正と API の機能強化に貢献します。Contribute bug fixes and enhancements to the API.
  • 公式のリリースで利用可能になる前に、修正プログラムや拡張機能を取得できます。Get fixes and enhancements before they are available in an official release.
  • API の最も包括的かつ最新の実装にアクセスし、それを参照用として使用するか、それを新しいプラットフォーム上の新しいライブラリを作成するために使用します。Access the most comprehensive and up-to-date implementation of the API, to use as a reference or to create new libraries on new platforms.

GitHub を通した皆様の貢献を歓迎いたします。We welcome your contributions via GitHub.

Exchange サーバーが必要になりますYou'll need an Exchange server

Exchange メールボックス アカウントを既に所有している場合は、このセクションを省略してもかまいません。それ以外の場合は、次のいずれかの方法で、初めての EWS クライアント アプリケーション用の Exchange メールボックスをセットアップします。If you already have an Exchange mailbox account, you can skip this section. Otherwise, you have the following options for setting up an Exchange mailbox for your first EWS client application:

Exchange からメールを送受信できることが確認できたら、開発環境をセットアップする準備ができています。Exchange Web クライアントの Outlook Web App を使用して、メールが送信できることを確認します。After you have verified that you can send and receive email from Exchange, you are ready to set up your development environment. You can use the Exchange web client Outlook Web App to verify that you can send email.

開発環境のセットアップSet up your development environment

以下にアクセスできることを確認してください。Make sure that you have access to the following:

  • .NET Framework 4 をサポートしているバージョンの Visual Studio。技術的には、どの C# コンパイラでも使用できるため Visual Studio は必ず必要であるというわけではありませんが、Visual Studio を使用することをお勧めします。Any version of Visual Studio that supports the .NET Framework 4. Although technically, you don't need Visual Studio because you can use any C# compiler, we recommend that you use it.

  • EWS マネージ API。システムに応じて、64 ビット バージョンと 32 ビット バージョンのどちらかをインストールします。既定のインストール場所を使用します。The EWS Managed API. You can use either the 64-bit or 32-bit version, depending on your system. Use the default installation location.

初めての EWS マネージ API アプリケーションの作成Create your first EWS Managed API application

次の手順は、Office 365 開発者向けサイトをセットアップすることを前提としています。Exchange をダウンロードしてインストールした場合、Exchange サーバーに有効な証明書をインストールするか、既定で提供されている自己署名証明書用に証明書の検証コールバックを実装する必要があります。なお、これらの手順は、使用している Visual Studio のバージョンによって若干異なる場合がありますのでご注意ください。These steps assume that you set up an Office 365 Developer Site. If you downloaded and installed Exchange, you will need to install a valid certificate on your Exchange server or implement a certificate validation callback for a self-signed certificate that is provided by default. Also note that these steps might vary slightly depending on the version of Visual Studio that you are using.

手順 1: Visual Studio でプロジェクトを作成するStep 1: Create a project in Visual Studio

  1. Visual Studio の [ファイル] メニューで、 [新規] を選択してから、 [プロジェクト] を選択します。 [新しいプロジェクト] ダイアログ ボックスが表示されます。In Visual Studio, on the File menu, choose New, and then choose Project. The New Project dialog box opens.

  2. C# コンソール アプリケーション を作成します。 [テンプレート] ウィンドウで、 [Visual C#] を選択してから、 [コンソール アプリケーション] を選択します。Create a C# Console Application. From the Templates pane, choose Visual C#, and then choose Console Application.

  3. プロジェクトに「HelloWorld」という名前を付けて、 [OK] を選択します。Name the project HelloWorld, and then choose OK.

Visual Studio は、プロジェクトを作成し、Program.cs コードのドキュメント ウィンドウを開きます。Visual Studio creates the project and opens the Program.cs code document window.

手順 2:EWS マネージ API の参照を追加するStep 2: Add a reference to the EWS Managed API

  1. [ソリューション エクスプ ローラー] ウィンドウが既に開いている場合、この手順を省略し、手順 2 に進みます。 [ソリューション エクスプ ローラー] ウィンドウを開くには、 [ビュー] メニューで [ソリューション エクスプ ローラー] を選択します。If the Solution Explorer window is already open, skip this step and proceed to step 2. To open the Solution Explorer window, on the View menu, choose Solution Explorer.

  2. [ソリューション エクスプ ローラー]HelloWorld プロジェクトで [参照] のショートカット メニュー (右クリック) を開き、コンテキスト メニューから [参照の追加] を選択します。プロジェクトの参照を管理するためのダイアログ ボックスが開きます。In the Solution Explorer and the HelloWorld project, open the shortcut menu (right-click) for References and choose Add Reference from the context menu. A dialog box for managing project references will open.

  3. [参照] オプションを選択します。Choose the Browse option. EWS マネージ API DLL がインストールされている場所を参照します。Browse to the location where you installed the EWS Managed API DLL. インストーラーによって設定された既定パスは、C:\Program Files\Microsoft\Exchange\Web Services<version>. です。The default path set by the installer is the following: C:\Program Files\Microsoft\Exchange\Web Services<version>. このパスは、32 ビットと 64 ビットのどちらのバージョンの Microsoft.Exchange.WebServices.dll をダウンロードするかによって異なります。The path can vary based on whether you download the 32 or 64 bit version of the Microsoft.Exchange.WebServices.dll. Microsoft.Exchange.WebServices.dll を選択し、[OK] または [追加] を選択します。Choose Microsoft.Exchange.WebServices.dll and select OK or Add. これによって、EWS マネージ API リファレンスがプロジェクトに追加されます。This adds the EWS Managed API reference to your project.

  4. EWS Managed API 2.0 を使用している場合は, .NET Framework 4 を対象とするよう HelloWorld プロジェクトを変更します。EWS マネージ API の他のバージョンでは、別の .NET Framework のターゲット バージョンを使用する可能性があります。If you are using EWS Managed API 2.0, change the HelloWorld project to target the .NET Framework 4. Other versions of the EWS Managed API might use a different target version of the .NET Framework.

  5. 正しい .NET Framework のターゲット バージョンを使用していることを確認します。 [ソリューション エクスプ ローラー] で、 HelloWorld プロジェクトのショートカット メニュー (右クリック) を開き、 [プロパティ] を選択します。 [ターゲット フレームワーク] ドロップダウン ボックスで、 [.NET Framework 4] が選択されていることを確認します。Confirm that you are using the correct target version of the .NET Framework. Open the shortcut menu (right-click) for your HelloWorld project in the Solution Explorer, and choose Properties. Verify that the .NET Framework 4 is selected in the Target framework drop-down box.

プロジェクトをセットアップし、EWS マネージ API への参照を作成したので、最初のアプリケーションを作成する準備ができました。Now that you have your project set up and you created a reference to the EWS Managed API, you are ready to create your first application. 簡潔にするために、Program.cs ファイルにコードを追加します。To keep things simple, add your code to the Program.cs file. EWS マネージ API の参照の詳細については、「EWS のマネージ API のアセンブリを参照する」を参照してください。Read How to: Reference the EWS Managed API assembly for more information about referencing the EWS Managed API. 次の手順では、ほとんどの EWS マネージ API クライアント アプリケーションを作成するための基本的なコードを開発します。In the next step, you will develop the basic code to write most EWS Managed API client applications.

手順 3:自動検出のための URL リダイレクト検証を設定します。Step 3: Set up URL redirection validation for Autodiscover

  • Main(string[] args) メソッドの後に、次のリダイレクト検証コールバック メソッドを追加します。これは、 自動検出によって返される、リダイレクトされた URL が HTTPS エンドポイントを表すかどうかを検証します。Add the following redirection validation callback method after the Main(string[] args) method. This validates whether redirected URLs returned by Autodiscover represent an HTTPS endpoint.

    private static bool RedirectionUrlValidationCallback(string redirectionUrl)
    {
       // The default for the validation callback is to reject the URL.
       bool result = false;
       Uri redirectionUri = new Uri(redirectionUrl);
       // Validate the contents of the redirection URL. In this simple validation
       // callback, the redirection URL is considered valid if it is using HTTPS
       // to encrypt the authentication credentials. 
       if (redirectionUri.Scheme == "https")
       {
          result = true;
       }
       return result;
    }
    

この検証コールバックは、手順 4 で ExchangeService オブジェクトに渡されます。アプリケーションが自動検出リダイレクトを信頼してそれに従うようにするには、これが必要です。自動検出リダイレクトの結果は、アプリケーションの EWS エンドポイントを提供します。This validation callback will be passed to the ExchangeService object in step 4. You need this so that your application will trust and follow Autodiscover redirects - the results of the Autodiscover redirect provides the EWS endpoint for our application.

手順 4:ExchangeService オブジェクトを準備するStep 4: Prepare the ExchangeService object

  1. using ディレクティブ参照を EWS マネージ API に追加します。Program.cs の上部の最後の using ディレクティブに次のコードを追加します。Add a using directive reference to the EWS Managed API. Add the following code after the last using directive at the top of Program.cs.

     using Microsoft.Exchange.WebServices.Data;
    
  2. Main メソッドで、対象とするサービス バージョンの ExchangeService オブジェクトをインスタン化します。この例では、EWS スキーマの初期のバージョンを対象とします。In the Main method, instantiate the ExchangeService object with the service version you intend to target. This example targets the earliest version of the EWS schema.

     ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
    
  3. Exchange オンプレミス サーバーを対象としており、クライアントがドメインに参加している場合は、手順 4 に進みます。クライアントが Exchange Online または Office 365 開発者向けサイトのメールボックスを対象としている場合、明示的な資格情報を渡す必要があります。 ExchangeService オブジェクトのインスタンス化の後ろに次のコードを追加し、メールボックス アカウントの資格情報を設定します。ユーザー名は、ユーザー プリンシパル名でなければなりません。手順 5 に進んでください。If you are targeting an on-premises Exchange server and your client is domain joined, proceed to step 4. If you client is targeting an Exchange Online or Office 365 Developer Site mailbox, you have to pass explicit credentials. Add the following code after the instantiation of the ExchangeService object and set the credentials for your mailbox account. The user name should be the user principal name. Proceed to step 5.

     service.Credentials = new WebCredentials("user1@contoso.com", "password");
    
  4. オンプレミス Exchange サーバーを対象とする、ドメインに参加しているクライアントは、ログオンしているユーザーの既定の資格情報を使用できます。ここでは、この資格情報がメールボックスに関連付けられていることを想定しています。 ExchangeService オブジェクトのインスタンス化の後ろに、次のコードを追加します。Domain-joined clients that target an on-premises Exchange server can use the default credentials of the user who is logged on, assuming the credentials are associated with a mailbox. Add the following code after the instantiation of the ExchangeService object.

     service.UseDefaultCredentials = true;
    

    クライアントが Exchange Online または Office 365 開発者向けサイトのメールボックスを対象とする場合、UseDefaultCredentials が既定値である false に設定されていることを確認します。クライアントは、EWS サービスを呼び出すサービス URL を取得するために自動検出サービスの最初の呼び出しを行う準備ができました。If your client targets an Exchange Online or Office 365 Developer Site mailbox, verify that UseDefaultCredentials is set to false, which is the default value. Your client is ready to make the first call to the Autodiscover service to get the service URL for calls to the EWS service.

  5. ExchangeService オブジェクトの AutodiscoverUrl メソッドは、自動検出サービスに対して一連の呼び出しを実行してサービス URL を取得します。このメソッドの呼び出しが成功した場合、 ExchangeService オブジェクトの URL プロパティがサービス URL を使用して設定されます。ユーザーのメール アドレスおよび RedirectionUrlValidationCallbackAutodiscoverUrl メソッドに渡します。手順 3 または 手順 4 で資格情報を指定したら、次のコードを追加します。 user1@contoso.com を使用するメール アドレスに変更し、自動検出サービスが EWS エンドポイントを検索できるようにします。The AutodiscoverUrl method on the ExchangeService object performs a series of calls to the Autodiscover service to get the service URL. If this method call is successful, the URL property on the ExchangeService object will be set with the service URL. Pass the user's email address and the RedirectionUrlValidationCallback to the AutodiscoverUrl method. Add the following code after the credentials have been specified in step 3 or 4. Change user1@contoso.com to your email address so that the Autodiscover service finds your EWS endpoint.

     service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
    

この時点で、EWS を呼び出してメールボックスのデータにアクセスできるようにクライアントが設定されています。At this point, your client is set up to make calls to EWS to access mailbox data. コードを今すぐ実行する場合は、ExchangeService.Url プロパティの内容を調べて、 AutodiscoverUrl メソッド呼び出しが動作することを確認してください。If you run your code now, you can verify that the AutodiscoverUrl method call worked by examining the contents of the ExchangeService.Url property. このプロパティに URL が含まれる場合、呼び出しは正常に行われています。If this property contains a URL, your call was a success! これは、アプリケーションが正常にサービスで認証され、メールボックスの EWS エンドポイントを検出したことを意味します。This means that your application successfully authenticated with the service and discovered the EWS endpoint for your mailbox. これで、初めての EWS の呼び出しを行う準備が整いました。Now you are ready to make your first calls to EWS. EWS URL の設定の詳細については、「EWS Managed API を使用して EWS サービス URL を設定する」を参照してください。Read How to: Set the EWS service URL by using the EWS Managed API for more information about setting the EWS URL.

手順 6:初めての Hello World メール メッセージを作成するStep 6: Create your first Hello World email message

  1. AutodiscoverUrl メソッド呼び出しの後に、新しい EmailMessage オブジェクトをインスタンス化し、作成したサービス オブジェクトに渡します。After the AutodiscoverUrl method call, instantiate a new EmailMessage object and pass in the service object you created.

     EmailMessage email = new EmailMessage(service);
    

    これで、サービス バインドが設定されているメール メッセージが作成されます。 EmailMessage オブジェクトで開始されるすべての呼び出しは、サービスの対象となります。You now have an email message on which the service binding is set. Any calls initiated on the EmailMessage object will be targeted at the service.

  2. 次に、メール メッセージの宛先行の受信者を設定します。これを行うには、 user1@contoso.com を変更して SMTP アドレスを使用します。Now set the To: line recipient of the email message. To do this, change user1@contoso.com to use your SMTP address.

     email.ToRecipients.Add("user1@contoso.com");
    
  3. メール メッセージの件名および本文を設定します。Set the subject and the body of the email message.

     email.Subject = "HelloWorld";
     email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API.");
    
  4. EWS マネージ API を使用して、最初のメール メッセージを送信する準備が整いました。You are now ready to send your first email message by using the EWS Managed API. Send メソッドは、サービスを呼び出し、配信用にメール メッセージを送信します。The Send method will call the service and submit the email message for delivery. Exchange と通信するために使用できる他の方法について詳しくは、「EWS マネージ API を使用して EWS と通信する」をお読みください。Read How to: Communicate with EWS by using the EWS Managed API to learn about other methods you can use to communicate with Exchange.

     email.Send();
    
  5. Hello World アプリケーションを実行する準備が整いました。Visual Studio で、 [F5] を選択します。空のコンソール ウィンドウが開きます。アプリケーションが認証を行い、自動検出リダイレクトに従い、自分自身に送信するメール メッセージを作成するための最初の呼び出しを行っている間、コンソール ウィンドウには何も表示されません。実行されている呼び出しを表示する場合は、 AutodiscoverUrl メソッドが呼び出される前のところに次の 2 行のコードを追加します。F5 キーを押します。これで、コンソール ウィンドウに EWS 要求と応答のトレースが出力されますYou are ready to run your Hello World application. In Visual Studio, select F5. A blank console window will open. You will not see anything in the console window while your application authenticates, follows Autodiscover redirections, and then makes its first call to create an email message that you send to yourself. If you want to see the calls being made, add the following two lines of code before the AutodiscoverUrl method is called. Then press F5. This will trace out the EWS requests and responses to the console window.

     service.TraceEnabled = true;
     service.TraceFlags = TraceFlags.All;
    

EWS マネージ API クライアント アプリケーションが作動するようになりました。利便性を考慮して、次の使用例では、Hello World アプリケーションを作成するために Program.cs に追加したすべてのコードを示します。You now have a working EWS Managed API client application. For your convenience, the following example shows all the code that you added to Program.cs to create your Hello World application.

using System;
using Microsoft.Exchange.WebServices.Data;
namespace HelloWorld
{
  class Program
  {
    static void Main(string[] args)
    {
      ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
      service.Credentials = new WebCredentials("user1@contoso.com", "password");
      service.TraceEnabled = true;
      service.TraceFlags = TraceFlags.All;
      service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
      EmailMessage email = new EmailMessage(service);
      email.ToRecipients.Add("user1@contoso.com");
      email.Subject = "HelloWorld";
      email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API");
      email.Send();
    }
    private static bool RedirectionUrlValidationCallback(string redirectionUrl)
    {
      // The default for the validation callback is to reject the URL.
      bool result = false;
      Uri redirectionUri = new Uri(redirectionUrl);
      // Validate the contents of the redirection URL. In this simple validation
      // callback, the redirection URL is considered valid if it is using HTTPS
      // to encrypt the authentication credentials. 
      if (redirectionUri.Scheme == "https")
      {
        result = true;
      }
      return result;
    }
  }
}

次の手順Next steps

最初の EWS マネージ API クライアント アプリケーションでより多くの作業を行う準備ができている場合、次のリソースを参照します。If you're ready to do more with your first EWS Managed API client application, explore the following resources:

カスタム アプリケーションで問題が発生したときには、質問やコメントをフォーラムに投稿してみてください (最初の投稿は忘れずにお読みください)。If you run into any issues with your application, try posting a question or comment in the forum (and don't forget to read the top post).

このセクションの内容In this section

関連項目See also