Export (0) Print
Expand All

How to: Get domain settings from an Exchange server

Exchange Server 2013

Learn how to get domain settings from an Exchange server by using the Autodiscover service.

Last modified: January 14, 2014

Applies to: EWS Managed API | Exchange Online | Exchange Server 2013 | Office 365

In this article
Prerequisites for getting domain settings
Core concepts for getting domain settings
Get domain settings by using the EWS Managed API
Get user settings by using EWS SOAP Autodiscover
Next steps
Additional resources

You can retrieve configuration information for an email domain by using the Autodiscover service. The Autodiscover service provides your application with a process for connecting to the correct service endpoint for a specific domain.

You can use one of the following development technologies to access the Autodiscover service:

  • The Exchange Web Services (EWS) Managed API

  • EWS

    If you are using EWS, you can use the following methods to retrieve user settings:

    • The SOAP-based Autodiscover service

    • The XML (POX) Autodiscover service

    • An autogenerated proxy generated from the SOAP or XML Autodiscover service

    For more information about these methods, see Autodiscover for Exchange.

The EWS Managed API provides an object-based interface for retrieving user settings. If your client application uses managed code, we recommend that you use the EWS Managed API. The EWS Managed API interface is better optimized for a simple object model than the typical autogenerated web service proxy.

If you are using EWS, we suggest that you use the SOAP Autodiscover service, because it supports a richer set of features than the POX Autodiscover service.

The Autodiscover service returns only the requested configuration settings. The following table lists the domain configuration settings that the Autodiscover service can return.

Table 1:  Domain configuration settings

Configuration setting

Description

ExternalEwsUrl

The external URL for EWS.

ExternalEwsVersion

The version of the Exchange server that hosts the EWS URL.

Before you create an application that connects to the Autodiscover service to get domain settings, make sure that you have access to the following:

  • Exchange Online, Exchange Online as part of Office 365, or a server running a version of Exchange starting with Exchange 2007. If you are using the EWS SOAP-based Autodiscover service, a server running a version of Exchange starting with Exchange 2010.

  • An Exchange server that is configured to accept connections from your client application. For information about how to configure your Exchange server, see Controlling client application access to EWS in Exchange.

  • An account that is authorized to use EWS. For information about how to configure an account, see Controlling client application access to EWS in Exchange.

Note Note

If you are using the EWS Managed API, you must provide a certificate validation callback in some circumstances. You may also need a certificate validation callback with some generated proxy libraries, such as those created by Visual Studio. For more information, see How to: Validate a server certificate for the EWS Managed API.

Core concepts for getting domain settings

Before you use Autodiscover to get domain settings, you should be familiar with the concepts listed in the following table.

Concept

Description

Autodiscover for Exchange

Provides an overview of how the Autodiscover service works.

How to: Use Autodiscover to find connection points

Describes the process used by the Autodiscover service to redirect your client application to the correct service endpoint.

If you are using the EWS Managed API, you use the Microsoft.Exchange.WebServices.Data.ExchangeService class in the Microsoft.Exchange.WebServices.Data namespace to manage your connection to EWS. The code examples in this section assume that you reference the following namespaces in your code:

  • System.Net

  • Microsoft.Exchange.WebServices.Data.ExchangeService

If you are using the EWS Managed API, you can use the Microsoft.Exchange.WebServices.Data.AutodiscoverSettings.GetUserSettings method of the Microsoft.Exchange.WebServices.Data.AutodiscoverService object to generate the request that retrieves configuration information for a domain, as shown in the following example. In this example, only some of the possible domain settings are requested, and only the requested settings are returned from the server.

AutodiscoverService autodiscoverService = new AutodiscoverService("domain.contoso.com");
autodiscoverService.Credentials = new NetworkCredential("User1", "password", "domain.contoso.com");

// Submit a request and get the settings. The response contains only the
// settings that are requested, if they exist.
GetDomainSettingsResponse domainresponse = autodiscoverService.GetDomainSettings(
    "domain",
    ExchangeVersion.Exchang2013,
    DomainSettingName.ExternalEwsUrl,
    DomainSettingName.ExternalEwsVersion);

You can parse the collection returned to access each key/value pair. The following example shows how to parse through each returned element and display the name and value of each key/value pair.

// Display each retrieved value. The settings are part of a key/value pair.
foreach (KeyValuePair<DomainSettingName, Object> domainsetting in domainresponse.Settings)
{
    Console.WriteLine(domainsetting.Key.ToString() + ": " + domainsetting.Value.ToString());
}

Alternatively, you can obtain the value of a specific setting. In the following example, the ExternalEwsUrl setting is to be displayed.

// Display a specific setting, such as ExternalEwsUrl.
Console.WriteLine(domainresponse.Settings[DomainSettingName.ExternalEwsUrl]);

The following example shows a SOAP XML request to get both domain settings from the Autodiscover service.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:a="http://schemas.microsoft.com/exchange/2010/Autodiscover" 
        xmlns:wsa="http://www.w3.org/2005/08/addressing" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <a:RequestedServerVersion>Exchange2013</a:RequestedServerVersion>
    <wsa:Action>http://schemas.microsoft.com/exchange/2010/Autodiscover/Autodiscover/GetDomainSettings</wsa:Action>
    <wsa:To>https://autodiscover.exchange.microsoft.com/autodiscover/autodiscover.svc</wsa:To>
  </soap:Header>
  <soap:Body>
    <a:GetDomainSettingsRequestMessage xmlns:a="http://schemas.microsoft.com/exchange/2010/Autodiscover">
      <a:Request>
        <a:Domains>
          <a:Domain>domain</a:Domain>
        </a:Domains>
        <a:RequestedSettings>
          <a:Setting>ExternalEwsUrl</a:Setting>
          <a:Setting>ExternalEwsVersion</a:Setting>
        </a:RequestedSettings>
        <a:RequestedVersion>Exchange2013</a:RequestedVersion>
      </a:Request>
    </a:GetDomainSettingsRequestMessage>
  </soap:Body>
</soap:Envelope>

The following example shows the XML response that is returned by the server after it parses the request from the client.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" 
        xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://schemas.microsoft.com/exchange/2010/
          Autodiscover/Autodiscover/GetDomainSettingsResponse</a:Action>
    <h:ServerVersionInfo xmlns:h="http://schemas.microsoft.com/exchange/2010/Autodiscover" 
          xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <h:MajorVersion>15</h:MajorVersion>
      <h:MinorVersion>0</h:MinorVersion>
      <h:MajorBuildNumber>160</h:MajorBuildNumber>
      <h:MinorBuildNumber>4</h:MinorBuildNumber>
      <h:Version>Exchange2013</h:Version>
    </h:ServerVersionInfo>
  </s:Header>
  <s:Body>
    <GetDomainSettingsResponseMessage xmlns="http://schemas.microsoft.com/exchange/2010/Autodiscover">
      <Response xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <ErrorCode>NoError</ErrorCode>
        <ErrorMessage />
        <DomainResponses>
          <DomainResponse>
            <ErrorCode>NoError</ErrorCode>
            <ErrorMessage>No error.</ErrorMessage>
            <DomainSettingErrors />
            <DomainSettings>
              <DomainSetting i:type="DomainStringSetting">
                <Name>ExternalEwsUrl</Name>
                <Value>https://failover.exchange.microsoft.com/ews/exchange.asmx</Value>
              </DomainSetting>
              <DomainSetting i:type="DomainStringSetting">
                <Name>ExternalEwsVersion</Name>
                <Value>15.00.0085.000</Value>
              </DomainSetting>
            </DomainSettings>
            <RedirectTarget i:nil="true" />
          </DomainResponse>
        </DomainResponses>
      </Response>
    </GetDomainSettingsResponseMessage>
  </s:Body>
</s:Envelope>

Domain settings provide the basic information that your client needs to connect to EWS. You can use this information to connect to EWS, or you can retrieve additional configuration settings for an email account from the server. For more information, see the following article:

Show:
© 2014 Microsoft