To perform the following procedures on a computer that has the Edge Transport server role installed, you must log on by using an account that is a member of the local Administrators group on that computer.

You must be familiar with how to create an address rewrite entry before you try to use comma-separated value (CSV) files to perform bulk imports of address rewrite entries. For information about how to create an address rewrite entry, see How to Create a New Address Rewrite Entry.

The following sections help you understand how to import address rewrite entries by using CSV files:

• Creating a CSV File   This section describes the required and optional fields in a CSV file that can be used to import address rewrite entries. The section also describes the specific requirements when you use the ExceptionList and OutboundOnly parameters in the CSV file.
  
  
• Understanding How CSV Files Are Used with the New-AddressRewriteEntry Cmdlet   This section explains how the Exchange Management Shell formats and then uses the data that is contained in the CSV file to import address rewrite entries.
  
  
• Importing a CSV File to Create Multiple Address Rewrite Entries   This section builds on the information in the previous sections with instructions about how to use the Exchange Management Shell commands that are required to import a CSV file and use it to create multiple address rewrite entries.
  
  

Creating a CSV File

First, you must create a CSV file that contains columns of values that correlate to the parameters that are required by the New-AddressRewriteEntry cmdlet. The following values are required by the New-AddressRewriteEntry cmdlet and therefore must have corresponding columns in the CSV file:

• Name   This parameter must be a string that uniquely identifies the address rewrite entry.
  
  
• InternalEmailAddress   This parameter specifies the internal Simple Mail Transfer Protocol (SMTP) address to be rewritten.
  
  
• ExternalEmailAddress   This parameter specifies the external SMTP address to be rewritten.
  
  

The following parameters are optional. You can include columns for them in the CSV file if you need them:

• ExceptionList   This parameter specifies the list of subdomains that should not be rewritten. No SMTP addresses contained within the specified subdomains are rewritten.
  
  
• OutboundOnly   This parameter specifies whether the address rewrite entry should rewrite SMTP addresses on messages that are inbound and outbound to the Exchange 2007 organization, or rewrite only those messages that are outbound from the Exchange 2007 organization.
  
  

If you specify values for the ExceptionList and OutboundOnly columns in the CSV file, every row must include a value in that column. For example, if you specify a value for the ExceptionList column in any row of the CSV file, all other rows in the CSV file must also contain a value in that column. This is because the ExceptionList parameter on the command line expects a value from the CSV file.

For more information about each parameter in these lists, see New-AddressRewriteEntry.

Specific Requirements When You Include the ExceptionList Parameter in a CSV File

If you want to create multiple address rewrite entries where some entries require values for the ExceptionList parameter and some entries do not, you must separate those address rewrite entries and create separate CSV files, and then import each of those CSV files. Also, you must enclose the values that are used with the ExceptionList parameter in double quotation marks ("). If you want to specify multiple domains that have the ExceptionList parameter, you must separate each value by using commas (,). For example, the string "domain1.com,domain2.com, domain3.com" contains three domains enclosed with double quotation marks and separated by commas.

Specific Requirements When You Include the OutboundOnly Parameter in a CSV File

If you specify values in the OutboundOnly column in one row of the CSV file, you must specify a value in the OutboundOnly column in every other row in the CSV file, just as with the ExceptionList parameter. However you can easily manage this requirement by specifying whether the OutboundOnly parameter should be True or False in each row.

Unlike Boolean usage elsewhere in the Exchange Management Shell, when you specify a value for the OutboundOnly parameter in a CSV file, you must specify a value of True or False, not $True or $False. This is because the value in the CSV file is manually converted to a Boolean value when the CSV file is interpreted on the command line.

For more information about when you must use the OutboundOnly parameter and how to use the OutboundOnly parameter, see the "Considerations for Use of Outbound-Only Address Rewriting" section in Planning for Address Rewriting.

Example of a CSV File with Optional Parameters Populated

The following example shows how a CSV file can be populated with the optional ExceptionList and OutboundOnly parameters included:

Copy Code

Name,InternalAddress,ExternalAddress,ExceptionList,OutboundOnly "Wingtip UK", *.wingtiptoys.co.uk, tailspintoys.com,"legal.wingtiptoys.co.uk,finance.wingtiptoys.co.uk,support.wingtiptoys.co.uk",True "Wingtip USA", *.wingtiptoys.com, tailspintoys.com,"legal.wingtiptoys.com,finance.wingtiptoys.com,support.wingtiptoys.com,corp.wingtiptoys.com",True "Wingtip Canada", *.wingtiptoys.ca, tailspintoys.com,"legal.wingtiptoys.ca,finance.wingtiptoys.ca,support.wingtiptoys.ca",True

The following example shows how a CSV file can be populated with the optional OutboundOnly parameter included:

Copy Code

Name,InternalAddress,ExternalAddress,OutboundOnly "Contoso Sales",*.sales.contoso.com,contoso.com,True "Contoso Research",*.research.contoso.com,contoso.com,True "Contoso UK",*.contoso.co.uk,contoso.com,True "Contoso Japan",*.contoso.co.jp,contoso.com,True "Contoso Support",support@adatum.com,support@contoso.com,False "Contoso Financial External",contosofinancial@woodgrovebank.com,financialinqueries@contoso.com,False

To import address rewrite entries by using CSV files, you must use the Import-Csv cmdlet. The Import-Csv cmdlet reads the CSV file and outputs each row in the CSV file as an array element and each column in the row as a property of that array element. You can see how this works by using the CSV file in "Example of a CSV File with Optional Parameters Populated" earlier in this topic. Import the example CSV file by using the following command, after you copy the text in the example into a file that is named example.csv:

	Copy Code
$CsvContents = Import-Csv c:\example.csv

Then, type the following command on the command line:

	Copy Code
$CsvContents

The following data is returned:

Copy Code

Name InternalAddress ExternalAddress OutboundOnly ---- --------------- --------------- ------------ Contoso Sales *.sales.contoso.com contoso.com True Contoso Research *.research.conto... contoso.com True Contoso UK *.contoso.co.uk contoso.com True Contoso Japan *.contoso.co.jp contoso.com True Contoso Support support@adatum.com support@contoso.com False Contoso Financia... contosofinancial... financialinqueri... False

If you want to view only the value that is contained in the InternalAddress column of the third row, you can use the following command:

	Copy Code
$CsvContents[2].InternalAddress

This returns the value *.contoso.co.uk.

Note:
Arrays always start at 0. Therefore, to retrieve the values from the third row, you must specify array element 2. For more information about arrays, see Arrays.

Understanding this example will make it easier for you to understand how the Exchange Management Shell processes the CSV file and uses it to pass data to the New-AddressRewriteEntry cmdlet.

As you can see in this example, each row in the CSV file becomes an array element, and each column becomes a property of that array element. By using the ForEach cmdlet, the Exchange Management Shell can move through the array automatically from start to finish and perform actions as each array element, in this case, one row from the CSV file, is encountered. After an array element has been passed to the ForEach cmdlet in the pipeline, the Exchange Management Shell can then access the properties that are stored within it. In this case, the properties are the columns that are contained on each row.

You can then use these properties to construct the New-AddressRewiteEntry command that is required to create address rewrite entries. The properties are named by using the column headings in the CSV file. They do not have to match the parameter name on the cmdlet. The following command is constructed from the explanation of this example:

	Copy Code
Import-Csv c:\example.csv | ForEach { New-AddressRewriteEntry -Name $_.Name -InternalAddress $_.InternalAddress -ExternalAddress $_.ExternalAddress -OutboundOnly ([Bool]::Parse($_.OutboundOnly)) -ExceptionList ($_.ExceptionList.Split(","))}

Note:
You don't have to assign an imported CSV file to a variable as was shown in the example at the beginning of this section. You can just include the Import-Csv cmdlet and pipe the output of that cmdlet to the ForEach cmdlet as shown in this example.

This command loops through each row in the example.csv file, and then uses the New-AddressRewriteEntry cmdlet to create address rewrite entries by using the parameter values obtained from the columns that exist in each row.

You probably noticed the $_ special variable in this command. The $_ special variable instructs the command to examine the current object in the pipeline. In this case, that is the current row of the CSV file.

The OutboundOnly and ExceptionList properties also have additional text surrounding their respective properties. The text ([Bool]::Parse($_.OutboundOnly)) instructs the Exchange Management Shell to interpret the string that is contained within the OutboundOnly property as a Boolean value. The text ($_.ExceptionList.Split(",")) instructs the Exchange Management Shell to split multiple values that are contained within the ExceptionList property by using commas. Without the text surrounding the ExceptionList property, the values that are contained in the ExceptionList property are treated as a single string, even if commas are present.

For more information about pipelining, see Pipelining.

Importing a CSV File to Create Multiple Address Rewrite Entries

Now that you understand what is going on behind the scenes, you can create a CSV file and use it to create multiple address rewrite entries. Create the CSV file that has at least the Name, InternalAddress, and ExternalAddress columns. If you want to specify values for the ExternalAddress and OutboundOnly parameters, add those columns also. Remember that every row must have a value in every column. For an example of a suitably formatted CSV file, see the examples in "Example of a CSV File with Optional Parameters Populated" earlier in this topic.

Use the following command syntax to create multiple address rewrite entries by using a CSV file:

	Copy Code
Import-Csv <CSV file path> | ForEach { New-AddressRewriteEntry -Name $_.<Name CSV column heading> -InternalAddress $_.<InternalAddress CSV column heading> -ExternalAddress $_.<ExternalAddress CSV column heading> -OutboundOnly ([Bool]::Parse($_.<OutboundOnly CSV column heading>)) -ExceptionList ($_.<ExceptionList CSV column heading>.Split(","))}

To use a CSV file in the Exchange Management Shell to create multiple address rewrite entries

1. Create and populate a CSV file that is named C:\ImportAddressRewriteEntries.csv

2. Run the following command:

   	Copy Code
   Import-Csv c:\ImportAddressRewriteEntries.csv | ForEach { New-AddressRewriteEntry -Name $_.Name -InternalAddress $_.InternalAddress -ExternalAddress $_.ExternalAddress -OutboundOnly ([Bool]::Parse($_.OutboundOnly)) -ExceptionList ($_.ExceptionList.Split(","))}

For detailed syntax and parameter information, see New-AddressRewriteEntry.