Creating an Administrative Session
Before you can create user accounts and view domain information, you'll need to create a valid administrative session. This works similarly to the way you might log into a secure administrative site, only instead of creating a valid session cookie, you'll be creating an authorized ticket. This process uses three API methods: GetLoginUrl
, and VerifyAuthData
. The GetLoginUrl
call simply returns the specific web address to which your application needs to post in order to create an authorized ticket. The address might change over time and can be different for each application used; however, by calling this method specifically, your code is abstracted from any unpredictable address changes. GetLoginDataTemplate
returns the string used specifically by the ticket-generating URL for passing in your administrating Live ID account name and its corresponding password. Note that the format for this string is quite specific. You must make a call to the GetLoginDataTemplate
method each time you authenticate to be sure you're conforming to the expected standards. Once the template is obtained, you'll need to replace the "Name" and "Password" placeholders with your own credentials. You'll then pass this new string to the URL provided in the GetLoginUrl
method using standard C# web classes to receive your valid session ticket. You then verify that no errors occurred by passing the ticket to the VerifyAuthData
method and, if valid, save the valid ticket and associate it with your web reference.
This may seem like a lot of work at first, but it becomes a no-brainer once you get used to it. In the Program.cs
file, add the following code directly below your static void Main
private static string CreateAuthTicket()
You'll call this function from the Main
method directly, isolating all of the requisite tasks for generating the ticket from the Main
|Author's Note: To keep this sample simple and easy to follow, all the code is in the Program.cs file. A more realistic example would likely separate most of the code into one or more classes.
You'll need a class-wide reference to the Admin Center Web reference, so go ahead and add the following declaration directly above the static void Main
static AdminCenterAPI.ManageDomain2 srvc;
Now you'll need to add the code from Listing 1
to the newly created CreateAuthTicket
If you follow the code you should find that each step reflects the process I just described. You first create a web object reference named srvc
that gives access to the Admin Center service endpoint. You then get the login URL and store it in a local string variable and get the login template as well. The code attempts to replace the template placeholders with your own account name and password, but you'll need to enter your own credentials where required. You then post the data to the provided URL and verify that it is valid. If valid, you create an instance of the ManageDomain2Authorization class, which is used by Admin Center to hold the authenticated ticket and deliver it to the web reference endpoint. You set the appropriate type (see Admin Center documentation about authentication types) and set the authentication value equal to your new ticket. Finally, you set the web reference's ManageDomain2AuthorizationValue
property equal to the instance of ManageDomain2Authorization, which contains the valid ticket.
If you try to compile this code as is, you'll get some errors. That's because you haven't yet implemented the PostwebData
method. This is a standard C# method that accepts a URL and a string template, posts the template to the URL, and returns whatever might come back from said post. Under the CreateAuthTicket
method, add the C# code from Listing 2
Go ahead and compile the code now and everything should come through fine. You're now ready to start creating your user accounts.
Adding New User Accounts
Since you're creating a Console Application, it might be best to provision some simple user I/O. Add Listing 3
to the static void Main
Again, this seems like a lot of code, but a closer look reveals this sample's simplicity. The first few lines write out a welcome message, then waits for users to click the Enter key to begin. The code then obtains the authorization ticket using the method you built in the last section. Next, the code gives the user a small menu of tasks from which to choose and sets up an empty switch block to pass focus to whichever function corresponds to the user's choice. The menu selection option is placed within a large while loop, allowing the user to come back and select other menu options once a previous selection's task has been completed. This pattern allows you to create individual methods that wrap your sample API calls without overlapping your application's control code.
Thinking back to your registration scenario, you'll want to tackle the "Add a New User" option first. This method will require the use of two Admin Center API methods: GetMemberNameState
. As discussed previously, a typical scenario demands that a user enters a desired name, which the system first checks for availability. If the name is not available, the user is appropriately told so, and then they are given the opportunity to try a different name. Upon finding an available user name, the system can garner some additional account info from the user and create the new account. Thus, the GetMemberNameState
method will be invoked each time a user enters a new name and the CreateMember
method is called only when an available name has been determined.
Replace the following code in the main switch block for case #1:
Add Listing 4
to your class.
Similar to the code in the static void Main
function, you begin with some simple text in the console followed by the beginning of a while loop. You use the loop to take the user back to the initial steps in the event that the user provided an unavailable name. Note that all of the code within the loop has been enclosed with a Try
block. There are a number of different errors that can be thrown by Microsoft when attempting to make an API call. Since there is no simple way to handle all of them gracefully, you simply catch any exception when thrown, print the contents of its message to the command line, and then go back to the main menu.
You next present the user with the option of entering a user name they would like to register. They must
enter the name as the fully qualified domain name. For example, a user wanting to register the name "Jake" will need to enter Jake@[your domain]
. Naturally you should feel free to tinker with the sample code to append the name with your URL as you see fit. Once entered, the system makes a call to GetMemberNameState
, passing in the user's desired name to check for its availability. The return value from this method is not a Boolean as one might expect. Rather, it is an enumeration with a value corresponding to the name's specific state within Windows Live. Although this code simply checks for availability, users should keep in mind that the GetMemberNameState
function can actually return one of five possible values:
- Blocked: The member name contains a blocked word.
- In Use: The member name is already registered with Windows Live.
- Hotmail Recycle: The member name was previously used as a Passport account with an associated Hotmail inbox and the account has not been recycled by the Hotmail back end.
- Existing EASI Account: The member name is an unmanaged EASI account and is registered with Windows Live. You can evict this account if you want to create a new account with this member name (this will force the existing EASI member to rename this account on next login).
If the desired username status is anything but Available
, the application displays a brief error message and allows the user to try to enter another name. When the user provides an available name, the application prompts the user to provide some optional account details to be saved with the new account name, such as first name, last name, an account password, and whether the user should be forced to change the account password upon their first login. When the user provides the data, the application passes it all to the CreateMember
method, and then takes the user back to the main menu.
As you can see, most of the code used in this example simply supports the input and makes it easy to step through. At the heart of the code lie iterative calls to the GetMemberNameState
method and a single call to the CreateMember
method. Thanks in part to the web reference framework provided by Visual Studio .NET 2008 (which created a proxy class and all of the plumbing needed to invoke the API calls), handling new accounts is as simple as entering a name and passing it to a function.
The rest of the code sample demonstrates other Admin Center API calls, prompting users for various bits of information and passing that information to other web methods. The "View Member List" option maps to a static function that makes a call to EnumMembers
. The "Reset Member Password" maps to another function that calls ResetMemberPassword
. Other mappings are similar. The samples are limited for the purpose of simplicity; however, readers should feel free to use this model to plug in functions that sample other methods. If you take a few minutes to explore the SDK documentation, you'll no doubt notice that a good number of the API methods are listed as "Restricted" and require Microsoft approval to use. Remember when I mentioned that Admin Center may provide extra features for different offer programs? These restricted functions were created specifically for these membership types, so most users won't be able to use them out of the box. Still, there are plenty of unrestricted methods available for you to use, with more on the way. Listing 5
contains the complete sample code.