Using Autodiscover to locate the correct endpoint
Last modified: December 10, 2012
Applies to: EWS Managed API | Exchange Server 2010
Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.
You can use the Autodiscover service to automatically configure Microsoft Exchange Server client applications to access the Client Access server, as well as provide configuration information to client applications. The Autodiscover service uses an e-mail address to locate the configuration information that is needed to create a connection to an Exchange server. Only a credentialed user of the domain can use the Autodiscover service.
If the URL of the Exchange Web Services (EWS) endpoint is already known, you do not have to use the Autodiscover service to make the connection. For information about how to connect to the server when the URL to the EWS endpoint is known, see Connecting to EWS by using the EWS Managed API 2.0.
Using the Autodiscover service to locate the correct endpoint
If the URL of the EWS endpoint is unknown, you can use the e-mail address of a user to determine the best endpoint. The following code shows how to explicitly set the URL of the Exchange.asmx file.
service.Url = new Uri("https://mail.Contoso.com/EWS/Exchange.asmx");
The following code shows how to use the Autodiscover service to set the service.Url to the Exchange.asmx file on the Exchange server that has the Client Access server role installed.
// Use Autodiscover to set the URL endpoint.
service.AutodiscoverUrl("User1@Contoso.com")
Request
The following code shows an example of the XML request that is sent to the Autodiscover service.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:a="https://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="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<a:RequestedServerVersion>Exchange2010</a:RequestedServerVersion>
<wsa:Action>https://schemas.microsoft.com/exchange/2010/Autodiscover/Autodiscover/GetUserSettings</wsa:Action>
<wsa:To>https://mail.microsoft.com/autodiscover/autodiscover.svc</wsa:To>
</soap:Header>
<soap:Body>
<a:GetUserSettingsRequestMessage xmlns:a="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<a:Request>
<a:Users>
<a:User>
<a:Mailbox>User1@Contoso.com</a:Mailbox>
</a:User>
</a:Users>
<a:RequestedSettings>
<a:Setting>InternalEwsUrl</a:Setting>
<a:Setting>ExternalEwsUrl</a:Setting>
</a:RequestedSettings>
</a:Request>
</a:GetUserSettingsRequestMessage>
</soap:Body>
</soap:Envelope>
Redirection response
The Autodiscover service tries to locate the Autodiscover endpoint for a given domain by using an e-mail account. If the e-mail account returns an HTTP 302 redirect, the Autodiscover service tries to follow the URL redirection. The following code shows an example of a redirection response from the server.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/" xmlns:a="http://www.w3.org/2005/08/addressing">
<s:Header>
<a:Action s:mustUnderstand="1">https://schemas.microsoft.com/exchange/2010/
Autodiscover/Autodiscover/GetUserSettingsResponse</a:Action>
<h:ServerVersionInfo xmlns:h="https://schemas.microsoft.com/exchange/2010/Autodiscover"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<h:MajorVersion>14</h:MajorVersion>
<h:MinorVersion>0</h:MinorVersion>
<h:MajorBuildNumber>682</h:MajorBuildNumber>
<h:MinorBuildNumber>1</h:MinorBuildNumber>
<h:Version>Exchange2010</h:Version>
</h:ServerVersionInfo>
</s:Header>
<s:Body>
<GetUserSettingsResponseMessage xmlns="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<Response xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorCode>NoError</ErrorCode>
<ErrorMessage />
<UserResponses>
<UserResponse>
<ErrorCode>RedirectAddress</ErrorCode>
<ErrorMessage>Redirection address.</ErrorMessage>
<RedirectTarget>User1@mail.Contoso.com</RedirectTarget>
<UserSettingErrors />
<UserSettings />
</UserResponse>
</UserResponses>
</Response>
</GetUserSettingsResponseMessage>
</s:Body>
</s:Envelope>
After a redirection, the client uses the redirection URL to prepare another request. The following code shows an example of the request.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:a="https://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="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<a:RequestedServerVersion>Exchange2010</a:RequestedServerVersion>
<wsa:Action>https://schemas.microsoft.com/exchange/2010/
Autodiscover/Autodiscover/GetUserSettings</wsa:Action>
<wsa:To>https://autodiscover.exchange.microsoft.com/autodiscover/autodiscover.svc</wsa:To>
</soap:Header>
<soap:Body>
<a:GetUserSettingsRequestMessage xmlns:a="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<a:Request>
<a:Users>
<a:User>
<a:Mailbox>User1@mail.Contoso.com</a:Mailbox>
</a:User>
</a:Users>
<a:RequestedSettings>
<a:Setting>InternalEwsUrl</a:Setting>
<a:Setting>ExternalEwsUrl</a:Setting>
</a:RequestedSettings>
</a:Request>
</a:GetUserSettingsRequestMessage>
</soap:Body>
</soap:Envelope>
The server has the correct e-mail address for the user and prepares a response. Only the requested user settings, InternalEwsUrl and ExternalEwsUrl, are returned. The following code shows an example of the response from the server.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:a="http://www.w3.org/2005/08/addressing">
<s:Header>
<a:Action s:mustUnderstand="1">https://schemas.microsoft.com/exchange/2010/
Autodiscover/Autodiscover/GetUserSettingsResponse</a:Action>
<h:ServerVersionInfo xmlns:h="https://schemas.microsoft.com/exchange/2010/Autodiscover"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<h:MajorVersion>14</h:MajorVersion>
<h:MinorVersion>1</h:MinorVersion>
<h:MajorBuildNumber>160</h:MajorBuildNumber>
<h:MinorBuildNumber>4</h:MinorBuildNumber>
<h:Version>Exchange2010_SP1</h:Version>
</h:ServerVersionInfo>
</s:Header>
<s:Body>
<GetUserSettingsResponseMessage xmlns="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<Response xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorCode>NoError</ErrorCode>
<ErrorMessage />
<UserResponses>
<UserResponse>
<ErrorCode>NoError</ErrorCode>
<ErrorMessage>No error.</ErrorMessage>
<RedirectTarget i:nil="true" />
<UserSettingErrors />
<UserSettings>
<UserSetting i:type="StringSetting">
<Name>InternalEwsUrl</Name>
<Value>https://server.Contoso.com/ews/exchange.asmx</Value>
</UserSetting>
<UserSetting i:type="StringSetting">
<Name>ExternalEwsUrl</Name>
<Value>https://server.Contoso.com/ews/exchange.asmx</Value>
</UserSetting>
</UserSettings>
</UserResponse>
</UserResponses>
</Response>
</GetUserSettingsResponseMessage>
</s:Body>
</s:Envelope>
Using the Autodiscover services to return other settings
You can use the Autodiscover services to return user settings other than InternalEwsUrl and ExternalEwsUrl, as well as domain settings, from the server. For more information, see Using Autodiscover to get user settings and Using Autodiscover to get domain settings.