Set-NAVTenant

Specifies settings for a tenant in a tenant database that is mounted on a Business Central Server instance.

Syntax

Set-NAVTenant
   [-Tenant] <TenantId>
   [-TenantDatabaseId] <TenantDatabaseId>
   [-BufferTenant]
   [-TimeoutSeconds <Int32>]
   [-Force]
   [-ServerInstance] <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-NAVTenant
   [-Tenant] <TenantId>
   [-AcquireExclusiveAccess]
   [-Justification] <String>
   [-Force]
   [-ServerInstance] <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-NAVTenant
   [-Tenant] <TenantId>
   [-ReleaseExclusiveAccess]
   [[-ExclusiveAccessTicket] <String>]
   [[-Justification] <String>]
   [-Force]
   [-ServerInstance] <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

There are two types of tenants: normal and buffer. A normal tenant is a tenant in the tenant database that can potentially be mounted on a Dynamics Server instance, and eventually used and managed in the production environment. Tenants are by default normal tenants. Changing a tenant from a normal tenant to a buffer tenant retains the tenant data as is, however the tenant is in a state that prevents it from being mounted until it is changed back to a normal tenant by using the Register-NAVTenant cmdlet.

You can use the Set-NAVTenant cmdlet to:

  • Change a specific tenant from a normal tenant to a buffer tenant.
  • Acquire or release exclusive access to a tenant.

Examples

EXAMPLE 1

Set-NAVTenant -ServerInstance NavServer -Tenant TenantA -TenantDatabaseId MyTenantDatabase -BufferTenant

This example changes the tenant with the ID 'TenantA' to a buffer tenant. The tenant database 'MyTenantDatabase' has been mounted on the Business Central Server instance 'NavServer' prior to running this cmdlet.

EXAMPLE 2

New-NAVTenant -ServerInstance NavServer -Tenant TenantB -TenantDatabaseId MyTenantDatabase
Mount-NAVTenant -ServerInstance NavServer -TenantId TenantB -TenantDatabaseId MyTenantDatabase
Copy-NAVTenantData -ServerInstance NavServer -SourceTenant TenantA -DestinationTenant TenantB
Set-NAVTenant -ServerInstance NavServer -Tenant TenantB -TenantDatabaseId MyTenantDatabase -BufferTenant

This example illustrates how to use a normal tenant (TenantA) as a template for creating one or more buffer tenants. The New-NAVTenant cmdlet creates a new empty normal tenant named 'TenantB' in the tenant database. The Copy-NAVTenantData cmdlet copies the data from 'TenantA' to 'TenantB'. Finally, the Set-NAVTenant cmdlet changes 'TenantB' to a buffer tenant. When needed, you can use the Register-NAVTenant cmdlet to change 'TenantB' to a normal tenant that can be mounted on a server instance.

EXAMPLE 3

$exlusiveAccessTicket = Set-NAVTenant -ServerInstance NavServer -TenantId TenantB -AcquireExcluisveAccess -Justification "Perform exclusive operation on tenant before dismount"

Set-NAVTenant -ServerInstance NavServer -TenantId TenantB -ReleaseExcluisveAccess -ExclusiveAccessTicket $exlusiveAccessTicket

This example illustrates how to acquire and release tenant exclusive access mode. You can use $exlusiveAccessTicket to perform operations on the tenant when it is in the exclusive access mode.

EXAMPLE 4

$exlusiveAccessTicket = Set-NAVTenant -ServerInstance NavServer -TenantId TenantB -AcquireExcluisveAccess -Justification "Perform exclusive operation on tenant before dismount"

Dismount-NAVTenant -ServerInstance NavServer -TenantId TenantB -ExclusiveAccessTicket $exlusiveAccessTicket

This example illustrates how to dismount a tenant when it is in the exclusive access mode. You do not have to explicitly release exclusive access mode for the dismounted tenant.

Parameters

-AcquireExclusiveAccess

Establishes exclusive access to the tenant. Any existing client sessions with the tenant are disconnected, and new sessions with the tenant are denied. Exclusive access is useful while upgrading the tenant because it prevents changes to data by other sessions. The cmdlet returns an exclusive access ticket, in the form of a text string. You will use the ticket to run other cmdlets that perform operations on the tenant, such as Dismount-NAVTenant. You also use the ticket when you release the tenant from exclusive access by using the -ReleaseExclusiveAccess parameter.

Type:SwitchParameter
Position:2
Default value:False
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-BufferTenant

The shared schema feature is for use in conjunction only with Microsoft hosted offerings in Dynamics 365, is unsupported in Business Central, and may not be used outside Dynamics 365.

Specifies to change the tenant to a buffer tenant.

The purpose of buffer tenants is to make it faster and more efficient to create new tenants (pre-populated with some basic data) on demand. For example, you will typically start with a normal tenant that contains basic or demonstration data that you want as a basis for new tenants. This tenant will act as a template for creating the buffer tenants. You can then use the New-NAVTenant, Copy-NAVTenantData, and Set-NAVTenant cmdlets to create a pool of buffer tenants in the tenant database, from which you can register to be new normal tenant as needed.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False
-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ExclusiveAccessTicket

Specifies the exclusive access ticket to use to release exclusive access. The ticket is returned when you acquire exclusive access by using the -AcquireExclusiveAccess parameter.

Type:String
Position:3
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-Force

Forces the command to run without asking for user confirmation. You can also use the -Force parameter to release exclusive access without specifying the -ExclusiveAccessTicket parameter, but you will have to set the -Justification parameter as well.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False
-Justification

Specifies a text string that provides a brief explanation for why you acquire or release exclusive access. The text is for informational/telemetry purposes.

To force release exclusive access instead of using the -ExclusiveAccessTicket parameter, you can use the -Justification parameter together with the -Force parameter.

Type:String
Position:4
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-ReleaseExclusiveAccess

Releases the tenant from exclusive access, allowing other client sessions to access the tenant. To release exclusive access, you must also either set the -ExclusiveAccessTicket or set the -Force and -Justification parameters.

Type:SwitchParameter
Position:2
Default value:False
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-ServerInstance

Specifies the name of a Business Central Server instance, for example, BC or myinstance. You can specify either the full name of an instance, such as MicrosoftDynamicsNavServer$myinstance or the short name such as myinstance.

Type:String
Position:0
Default value:None
Accept pipeline input:True (ByPropertyName, ByValue)
Accept wildcard characters:False
-Tenant

Specifies the ID of the tenant that you want to change. If you are changing the tenant to be a buffer tenant, the tenant cannot be mounted on the Business Central Server Instance; otherwise you will get an error.

Type:TenantId
Aliases:Id
Position:1
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-TenantDatabaseId

Specifies the ID of the tenant database that contains the tenant that you want to change. The tenant database must be mounted on the Business Central Server instance.

Type:TenantDatabaseId
Position:2
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-TimeoutSeconds

Specifies the minimum amount of seconds to keep trying in case of transient errors, such as when the database is temporarily offline. It defaults to the default Business Central internal timeouts for different error types.

Type:Int32
Position:Named
Default value:0
Accept pipeline input:False
Accept wildcard characters:False
-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Inputs

Microsoft.Dynamics.Nav.Types.TenantId

By property name: Tenant

Microsoft.Dynamics.Nav.Types.TenantDatabaseId

By property name: TenantDatabaseId

System.Management.Automation.SwitchParameter

By property name: AcquireExclusiveAccess

System.Management.Automation.SwitchParameter

By property name: AcquireExclusiveAccess

System.String

By property name: ExclusiveAccessTicket

System.String

By property name: Justification

System.String

ServerInstance