Documentation Error - Set-VBRJobAdvancedOptions

[ratkinsonuk]

I've been hacking away at finding how to enable the 'Remove deleted items data after' setting in the Storage Advanced options. The documentation (https://helpcenter.veeam.com/docs/backu ... ml?ver=100) states "NOTE: You cannot enable the retention policy for deleted VMs with Veeam PowerShell".

Reading through this thread - powershell-f26/is-enablescheduler-alway ... 47762.html - that's actually not the case, and I was able to do this....

PS > $BackupJobOptions = Get-VBRJobOptions -Job $BackupJobName
$BackupJobOptions.BackupStorageOptions.RetainCycles = 10
$BackupJobOptions.BackupStorageOptions.EnableDeletedVmDataRetention = $true
Set-VBRJobOptions -Job $BackupJobName -Options $BackupJobOptions | Out-Null
PS >

[oleg.feoktistov]

Hi Robert,

Veeam Powershell guide references only supported methods to manage your VBR environment. The switch you found does exists, but it lays further down on .NET level. It is not considered as a best practice to change object properties manually like in C# or else. That's what parameters are for. The note you emphasised on implies that there is no official way documented in Veeam Powershell guide to change that option.

Thanks,
Oleg

[ratkinsonuk]

Hi Oleg. I see what you are saying.

One thing though - if setting properties directly rather than using a pre-designed method (e.g. Set-VMRetention), then why do you provide the Set-VBRJobOptions() cmdlet? What 'options' is it OK to change with this method? Shoudn't that cmdlet carry a warning message in the documentation also?

[oleg.feoktistov]

Hi Robert,

You have a point. If you skim through the types for objects reflected with some cmdlets, such as Get-VBRJob, Get-VBRBackup, Get-VBRRestorePoint etc., you'll notice that object type name starts with C (CBackupJob, CBackup, COib), which means Core. Some of these types were developed a long ago (for v7-8 version) and have their properties exposed through Powershell in every way. Now we stick to best practices, when we have a separate namespace for types retrievable with Powershell (with VBR prefix) and strictly parametrised cmdlets for them with as less dynamic/static methods as possible. At that time, I believe, these guiding points weren't duly considered or even developed. And since Set-VBRJobOptions can literally change almost any non-read-only property of a job, it would involve a huge amount of parameters and long-lasting considerations on how to implement them.
But since some time it is all clear and we aim at parametrising cmdlets as much as possible. Sooner or later, we hope to implement the same practices for Set-VBRJobOptions, as we did with Set-VBRComputerBackupJob and other cmdlets.
For now, it is ok to work with Set-VBRJobOptions since we have no other way around, but I'm bethinking more and more that we would need to determine all such cmdlets and consider their deprecation soon enough, offering something more clear instead. I do agree that checking cmdlet syntax in the guide, feeling confused and then appealing to the forums for scripts on changing precise options or diving into Powershell ISE intellisense tips is not the best way here.

Kind regards,
Oleg

[ratkinsonuk]

It does make me wonder why the developers don't want that particular setting changed outside the GUI, and what could break in the future. I'm guessing there must be something else going on in the GUI code that isn't part of simply setting the property.

Whilst we're talking about the cmdlet's in general, I'd like to give you some feedback on their structure and the documentation. To give you some background, I've been a programmer for about 40 years, but only just started dabbling with Powershell and the B&R cmdlet's.

It's taken me around 4 full days to put together some scripts (bespoke to us) to create new repositories and new backup jobs. I'd say 80% of that time wasn't me struggling with Powershell, but trying to work out how the settings in the GUI relate to the relevant cmdlet.

My point is, if the documentation could be better structured to follow the GUI, then you wouldn't have to hunt for the right command, just follow the tree down. So, instead of....

Veeam PowerShell Reference>Veeam PowerShell Reference>Jobs>VSS Options>Get-VBRJobObjectVssOptions

.....you would follow.....

Veeam PowerShell Reference>Backup & Recovery >Jobs>Guest Porcessing>Applications>General>Get-VBRJobObjectVssOptions


Just a thought!

[oleg.feoktistov]

Hi Robert,

It does make me wonder why the developers don't want that particular setting changed outside the GUI, and what could break in the future. I'm guessing there must be something else going on in the GUI code that isn't part of simply setting the property.

Yes, in fact, GUI code has a separate namespace.
Well, it's generally not the best practice to let APIs like Powershell operate over core parts of the code directly.
It should have a distinct contract, namespace and getters/setters. Otherwise, it could lead to incompatibility scenarios, when the core code is changed and you are bound to amend powershell scripts, where you used core classes. On the contrary, using classes meant for powershell, you wouldn't even notice changes on the core side unless it is a major update for a cmdlet. But it is considered a breaking change and we usually don't do that for powershell.

As for the documentation, you can always click on "Send feedback" button on the bottom of any article page to share your thoughts with the writers team directly.

Thanks,
Oleg

[ratkinsonuk]

> you can always click on "Send feedback" button on the bottom of any article page

I hadn't spotted that one, but I'll do it now.