Applies to: Exchange Server 2013, Exchange Online

Topic Last Modified: 2013-02-21

Use the New-App cmdlet to install apps for Outlook.

For information about the parameter sets in the Syntax section below, see Syntax.

Syntax

New-App [-MarketplaceAssetID <String>] [-MarketplaceQueryMarket <String>] [-MarketplaceServicesUrl <String>] <COMMON PARAMETERS>
New-App [-FileData <Byte[]>] <COMMON PARAMETERS>
New-App [-FileStream <Stream>] <COMMON PARAMETERS>
New-App [-Url <Uri>] <COMMON PARAMETERS>
COMMON PARAMETERS: [-Confirm [<SwitchParameter>]] [-DefaultStateForUser <Enabled | Disabled | AlwaysEnabled>] [-DomainController <Fqdn>] [-DownloadOnly <SwitchParameter>] [-Enabled <$true | $false>] [-Mailbox <MailboxIdParameter>] [-OrganizationApp <SwitchParameter>] [-ProvidedTo <Everyone | SpecificUsers>] [-UserList <MultiValuedProperty>] [-WhatIf [<SwitchParameter>]]

Examples

EXAMPLE 1

This example installs the Finance Test app manifest file that has been copied to the local hard disk.

Copy Code 
$Data=Get-Content -Path "C:\Apps\FinanceTestApp.xml" -Encoding Byte -ReadCount 0
Copy Code 
New-App -FileData $Data

For more information, see Install or Remove Apps for Outlook for Your Organization.

EXAMPLE 2

This example installs the Contoso CRM app manifest.xml from a URL on the Contoso corporate network. The Exchange server must be able to reach the target URL. This app is installed as an organization app and made available to a specific set of users in the organization, and is enabled for those users by default.

Copy Code 
New-App -OrganizationApp -Url https://Server01.Contoso.com/apps/ContosoCRMApp/manifest.xml -ProvidedTo SpecificUsers -UserList "user1,user2,user3,user4,user5" -DefaultStateForUser Enabled

For more information, see Install or Remove Apps for Outlook for Your Organization.

Detailed Description

If the app is enabled for the entire organization, users can activate the new app when viewing mail or calendar items within Microsoft Outlook or Microsoft Office Outlook Web App. If an installed app isn't enabled, users can enable the app from Outlook Web App Options. Similarly, if an app is installed, an administrator can enable the app from the Exchange Administration Center or by using the Enable-App or Set-App cmdlet.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Apps for Outlook" entry in the Recipients Permissions topic.

Parameters

Parameter Required Type Description

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm switch.

DefaultStateForUser

Optional

Microsoft.Exchange.Management.Extension.DefaultStateForUser

The DefaultStateForUser parameter specifies the default initial state of the organization app for the provided users. This parameter is set to Disabled by default. If set to AlwaysEnabled, users can't disable the app for themselves. You must use the OrganizationApp parameter when you use this parameter.

The possible values are:

  • Enabled

  • Disabled

  • AlwaysEnabled

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.

DownloadOnly

Optional

System.Management.Automation.SwitchParameter

The DownloadOnly switch specifies whether to get the app manifest file and prompt the user for confirmation before committing to actual installation. This is set to $false by default. If the DownloadOnly parameter is set to $true, the cmdlet only downloads the app manifest file (and displays the app properties) without installing the app.

Enabled

Optional

System.Boolean

The Enabled parameter specifies whether the app is made available to users in the organization. By default, this is set to $true.

Caution:
This setting overrides the ProvidedTo, UserList, and DefaultStateForUser settings.This setting doesn't prevent users from installing their own instance of the app if the user has install permissions.

This parameter may be set to the following values:

  • $true   The app is enabled for the specified users in the organization. This makes the app available for the specified users.

  • $false   The app isn't enabled for any users in the organization. This hides the app from all users in the organization.

FileData

Optional

System.Byte[]

The FileData parameter specifies the location of the app manifest file. You must specify only one source location for the app manifest file. You can specify the app manifest file by using the MarketplaceServicesUrl, Url, or FileData parameter. If you use this parameter, use the Get-Content cmdlet and this cmdlet together as shown in the example.

FileStream

Optional

System.IO.Stream

The FileStream parameter can't be used in the Exchange Management Shell. It's used to support the app uploader and is only used by the Exchange admin center.

Mailbox

Optional

Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter

The Mailbox parameter specifies the identity of the mailbox or mail user. You can use the following values:

  • GUID

  • Distinguished name (DN)

  • Domain\Account

  • User principal name (UPN)

  • Legacy Exchange DN

  • SMTP address

  • Alias

MarketplaceAssetID

Optional

System.String

The MarketplaceAssetID parameter specifies the office store identifier for the app. This parameter is required if the MarketplaceServicesUrl parameter is specified.

MarketplaceQueryMarket

Optional

System.String

The MarketplaceQueryMarket parameter specifies the locale that an app is filed under at the office marketplace. For example, an app for the United States market in English uses the value en-US. If not specified, this value is set to en-US.

MarketplaceServicesUrl

Optional

System.String

The MarketplaceServicesUrl parameter specifies the full services URL for the app. You must specify only one source location for the app manifest file. You can specify the app manifest file by using the MarketplaceServicesUrl, Url, or FileData parameter.

OrganizationApp

Optional

System.Management.Automation.SwitchParameter

The OrganizationApp parameter specifies the apps that are installed for the organization (not bound to a specific user). This is set to $false by default.

ProvidedTo

Optional

Microsoft.Exchange.Data.ApplicationLogic.Extension.ClientExtensionProvidedTo

The ProvidedTo parameter specifies the availability of an app in your organization. By default, new apps are available to all users in your organization. You must use the OrganizationApp parameter when you use this parameter. The following are the possible values:

  • Everyone   This app is provided to every user in the organization. Every user sees this app listed in the installed apps list in Outlook Web App Options. When apps in the installed apps list display as enabled, users can use the features of this app in their email. All users are blocked from installing their own instances of this app, including but not limited to users with install apps permissions.

  • SpecificUsers   This app is provided to only the users specified using the UserList parameter. Users that aren't specified don't see this organizational app in their management view, nor will it activate in their mail or calendar items. Specified users are also blocked from installing their own instance of this app. Users that aren't listed aren't blocked from installing their own instance of this app.

Url

Optional

System.Uri

The Url parameter specifies the full URL location of the app manifest file you want to install. You must specify only one source location for the app manifest file. You can specify the app manifest file by using the MarketplaceServicesUrl, Url, or FileData parameter.

UserList

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The UserList parameter specifies the list of users that are granted access to the organizational app. Use the UserList parameter to specify the users that you want to use the app.You must use the OrganizationApp parameter when you use this parameter. You can use the following values:

  • GUID

  • DN

  • Domain\account

  • UPN

  • Legacy Exchange DN

  • SMTP address

  • Alias

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf switch.

Input Types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

Return Types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.