ICachingExternalSettingsProvider Interface
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Controls an external settings region that caches its state in memory because reading, writing, or monitoring the backing store is too expensive. The external settings provider must implement this (instead of just IExternalSettingsProvider) if the registration specifies realtimeNotifications = false.
public interface ICachingExternalSettingsProvider : Microsoft.VisualStudio.Utilities.UnifiedSettings.IExternalSettingsProvidertype ICachingExternalSettingsProvider = interface
interface IExternalSettingsProviderPublic Interface ICachingExternalSettingsProvider
Implements IExternalSettingsProvider- Implements
Methods
| CommitPendingChangesAsync(CancellationToken) |
Persist any in-memory changes to the backing store. Normally this will be called after each change, but in some "batch" scenarios, this could be preceded by multiple calls to SetValueAsync<T>(String, T, CancellationToken). There is no need to raise SettingValuesChanged for changes to the backing store made via this method, but it's OK if you do. This will always be preceded closely by a call to RefreshCacheAsync(CancellationToken) so it's reasonable for the setting owner to assume that the backing store probably hasn't been updated since the last refresh. Therefore, conflict detection and resolution isn't necessary unless 100% protection against data loss is required; you can just write the cache directly to the backing store. |
| GetEnumChoicesAsync(String, CancellationToken) |
Gets the choices to show in a dynamic enum setting. (Inherited from IExternalSettingsProvider) |
| GetMessageTextAsync(String, CancellationToken) |
Gets the current text of a dynamic message. (Inherited from IExternalSettingsProvider) |
| GetValueAsync<T>(String, CancellationToken) |
Gets the current value of a registered setting in this external region. (Inherited from IExternalSettingsProvider) |
| OpenBackingStoreAsync(CancellationToken) |
An external settings region's registration includes the ID of a string resource describing the backing store, like "In-memory only; resets on restart" or "Managed by NuGet.config". When the backing store is something that can be edited directly, like a text file, that string can surround the store name with '%', like "Managed by %NuGet.config%". The %-delimited span will be rendered as a link, and when it is clicked, Unified Settings will call this method. This method should open the backing store in an editor. (Inherited from IExternalSettingsProvider) |
| RefreshCacheAsync(CancellationToken) |
Reload the backing store into memory, updating any in-memory cached values. This method should raise SettingValuesChanged if any settings changed during the refresh. You can pass SomeOrAll if you don't know whether any settings changed. |
| SetValueAsync<T>(String, T, CancellationToken) |
Sets the value of a registered setting in this external region. If the external settings region has realtimeNotifications = false and this objects implements ICachingExternalSettingsProvider, this can update an in-memory cache without affecting the backing store (until CommitPendingChangesAsync(CancellationToken) is called). Otherwise, this method should update the backing store immediately. (Inherited from IExternalSettingsProvider) |
Events
| DynamicMessageTextChanged |
Raised by the setting owner when the text of a dynamic message should be updated in the UI. This will result in a callback to GetMessageTextAsync(String, CancellationToken). (Inherited from IExternalSettingsProvider) |
| EnumSettingChoicesChanged |
Raised by the setting owner when the choices for an enum setting should be updated in the UI. This will result in a callback to GetEnumChoicesAsync(String, CancellationToken). (Inherited from IExternalSettingsProvider) |
| ErrorConditionResolved |
Raised by the setting owner when an error state affecting the entire external settings region (i.e. one with Scope == EntireRegion or Unknown) is resolved. This will trigger Unified Settings to remove the error UI and refresh the region. (Inherited from IExternalSettingsProvider) |
| SettingValuesChanged |
Raised by the setting owner when one or more settings change in the backing store. This can also be raised to indicate that an error state affecting a single setting (i.e. one with Scope == SingleSettingOnly) has been resolved. (Inherited from IExternalSettingsProvider) |