Set-NAVTenant

Sets the tenant to acquire or release exclusive access. NOTE: This cmdlet also supports shared-schema operations that are for internal use only. These operations can't be used on Business Central on-premises tenants.

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>]
Set-NAVTenant
   [-Tenant] <TenantId>
   [-Force]
   -Compression <CompressionType>
   [-ServerInstance] <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

When exclusive access is acquired by a 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.

FOR INTERNAL USE ONLY: When using shared schema, 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.

Examples

EXAMPLE 1

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

FOR INTERNAL USE ONLY: 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 'BCServer' prior to running this cmdlet.

EXAMPLE 2

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

FOR INTERNAL USE ONLY: 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

$exclusiveAccessTicket = Set-NAVTenant -ServerInstance BCServer -Tenant TenantB -Justification "Perform exclusive operation on tenant before dismount" -AcquireExclusiveAccess
Set-NAVTenant -ServerInstance BCServer -Tenant TenantB -ExclusiveAccessTicket $exclusiveAccessTicket -ReleaseExclusiveAccess

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

EXAMPLE 4

$exclusiveAccessTicket = Set-NAVTenant -ServerInstance BCServer -Tenant TenantB -Justification "Perform exclusive operation on tenant before dismount" -AcquireExclusiveAccess
Dismount-NAVTenant -ServerInstance BCServer -Tenant TenantB -ExclusiveAccessTicket $exclusiveAccessTicket

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
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-BufferTenant

FOR INTERNAL USE ONLY: 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
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Compression

Specifies the compression level to use for the tenant database. Actual compression is only enabled for new tables. Existing tables can be compressed with Start-NAVDatabaseCompression.

Possible values: Unspecified, None, Row, Page

Type:CompressionType
Accepted values:Unspecified, None, Row, Page
Position:Named
Default value:Unspecified
Required:True
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
Required:False
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
Required:False
Accept pipeline input:True
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
Required: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
Required:True
Accept pipeline input:True
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
Required:True
Accept pipeline input:True
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 MicrosoftDynamicsBCServer$myinstance or the short name such as myinstance.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
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
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-TenantDatabaseId

FOR INTERNAL USE ONLY: 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
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-TimeoutSeconds

FOR INTERNAL USE ONLY: 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
Required:False
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
Required:False
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