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
BufferTenant (Default)
Set-NAVTenant
[-Tenant] <TenantId>
[-TenantDatabaseId] <TenantDatabaseId>
[-ServerInstance] <String>
[-BufferTenant]
[-TimeoutSeconds <Int32>]
[-Force]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
AcquireExclusiveAccess
Set-NAVTenant
[-Tenant] <TenantId>
[-Justification] <String>
[-ServerInstance] <String>
[-AcquireExclusiveAccess]
[-Force]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
ReleaseExclusiveAccess
Set-NAVTenant
[-Tenant] <TenantId>
[[-ExclusiveAccessTicket] <String>]
[[-Justification] <String>]
[-ServerInstance] <String>
[-ReleaseExclusiveAccess]
[-Force]
[-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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
AcquireExclusiveAccess
| Position: | 2 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
BufferTenant
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ReleaseExclusiveAccess
| Position: | 3 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
AcquireExclusiveAccess
| Position: | 4 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ReleaseExclusiveAccess
| Position: | 2 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | TenantId |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | Id |
Parameter sets
(All)
| Position: | 1 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | TenantDatabaseId |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
BufferTenant
| Position: | 2 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | Int32 |
| Default value: | 0 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
BufferTenant
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
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