My.Settings Object
Provides properties and methods for accessing the application's settings.
The My.Settings object provides access to the application's settings and allows you to dynamically store and retrieve property settings and other information for your application. For more information, see Managing Application Settings.
Properties
The properties of the My.Settings object provide access to your application's settings. To add or remove settings, use the Settings Designer. For more information, see How to: Add or Remove Application Settings.
Each setting has a Name, Type, Scope, and Value, and these settings determine how the property to access each setting appears in the My.Settings object:
-
Name determines the name of the property.
-
Type determines the type of the property.
-
Scope indicates if the property is read-only. If the value is Application, the property is read-only; if the value is User, the property is read-write.
-
Value is the default value of the property.
Methods
|
Method |
Description |
|
Reload |
Reloads the user settings from the last saved values. |
|
Save |
Saves the current user settings. |
The My.Settings object also provides advanced properties and methods, inherited from the ApplicationSettingsBase class.
The following table lists examples of tasks involving the My.Settings object.
|
To |
See |
|
Read an application setting |
|
|
Change a user setting |
|
|
Persist user settings |
|
|
Create a property grid for user settings |
How to: Create Property Grids for User Settings in Visual Basic |
This example displays the value of the Nickname setting.
For this example to work, your application must have a Nickname setting, of type String. For more information, see How to: Add or Remove Application Settings.
NOTE: At least 1 dummy Setting must be defined in the Designer, so there will be "LocalFileSettingsProvider" defined.
' -- Application Settings Name Suffixes
Public Const SN_WinState = "WinState"
Public Const SN_WinLocation = "WinLocation"
Public Const SN_WinSize = "WinSize"
''' <summary>
''' Add (if necessary) a My.Setting Definition using the specified Setting Name (SetngNameStr)
''' Default Value (DfltValueObj), User Scoped? Flag (UserScopedBool) and Roaming? Flag (RoamingBool).
''' NOTE: For Dynamically (vs. Designer) added Settings, My.Settings (SetngNameStr) will not exist until
''' you try to Dynamically add it again, then its previously Save'd (in *.Config) value will (poof!) appear!?!
''' WARNINGS:
''' 1) At least 1 dummy Setting must be defined in the Designer, so there will be
''' a "LocalFileSettingsProvider" defined.
''' 2) Does not call My.Settings.Save, so you can call it after all Settings are created when
''' loading Settings and / or at your normal Save point when saving Settings. You can check to see if
''' My.Settings.Properties.Count has changed after all your calls are done to do a one-time Save.
''' </summary>
''' <param name="SetngNameStr"></param>
''' <param name="DfltValueObj"></param>
''' <param name="UserScopedBool"></param>
''' <param name="RoamingBool"></param>
''' <remarks></remarks>
Public Sub AddMySetting( _
ByVal SetngNameStr As String, _
ByRef DfltValueObj As Object, _
Optional ByVal UserScopedBool As Boolean = True, _
Optional ByVal RoamingBool As Boolean = False _
)
Const DfltMySetngsProvdrNameStr As String = "LocalFileSettingsProvider"
' -- Used to determine if Dynmically Created Setting was previously Save'd.
Const DummyDfltSetngValueObj As Object = Nothing
With My.Settings
' -- If Setting Definition Not Found In Memory.
' -- NOTE: A dynamically created Setting must be redefined every time you restart the App
' -- (by re-adding its definition to My.Settings.Properties). Then, if it was previously
' -- saved() in a *.Config File, its saved value will appear in the My.Settings
' -- .PropertyValues and .Items Properties.
If .Properties.Item(SetngNameStr) Is Nothing Then
' -- Setting either needs to be or was dynamically created.
Dim SetngAttrsDict As New Configuration.SettingsAttributeDictionary
If UserScopedBool Then
SetngAttrsDict.Add( _
key:=GetType(Configuration.UserScopedSettingAttribute), _
value:=New Configuration.UserScopedSettingAttribute() _
)
Else ' -- UserScopedBool
SetngAttrsDict.Add( _
key:=GetType(Configuration.ApplicationScopedSettingAttribute), _
value:=New Configuration.ApplicationScopedSettingAttribute() _
)
End If ' -- Else Not (UserScopedBool)
If RoamingBool Then
SetngAttrsDict.Add( _
key:=GetType(Configuration.SettingsManageabilityAttribute), _
value:=New Configuration.SettingsManageabilityAttribute(Configuration.SettingsManageability.Roaming) _
)
End If ' -- RoamingBool
' -- Add/re-add Setting Definition to in-memory Settings Definitions (My.Settings.Properties)
' -- with a Dummy Default Value that wouldn't normally be used (i.e. Nothing). If the
' -- resulting Setting Value (in My.Settings .Items (SetngNameStr) or .PropertyValues.Item
' -- (SetngNameStr).PropertyValue) is still the Dummy Default Value, that means it needs to be
' -- created / saved. If not, it will be the previously created and saved value.
Dim SetngPropObj As New Configuration.SettingsProperty( _
Name:=SetngNameStr, _
propertyType:=DfltValueObj.GetType, _
provider:=.Providers.Item(DfltMySetngsProvdrNameStr), _
isreadonly:=False, _
defaultvalue:=DummyDfltSetngValueObj, _
serializeas:=Configuration.SettingsSerializeAs.String, _
attributes:=SetngAttrsDict, _
throwOnErrorDeserializing:=True, _
throwOnErrorSerializing:=True _
)
.Properties.Add(SetngPropObj)
' -- If Setting's Value is still the Dummy Default Value,
If .Item(SetngNameStr) Is DummyDfltSetngValueObj Then
' -- Add the Real Default Value to the in-memory Settings.
.PropertyValues.Item(SetngNameStr).PropertyValue = DfltValueObj
End If
End If ' -- Setting Definition Not In Memory
End With ' -- My.Settings
End Sub
''' <summary>
''' Add (if necessary) and get a My.Setting Defintion and its Value, respectively, using the specified
''' Setting Name (SetngNameStr), Destination Value (DestValueObj), User Scoped? Flag (UserScopedBool)
''' and Roaming? Flag (RoamingBool).
''' If SetngNameStr's Definition doesn't exist, add it using DestValueObj as the Default Value.
''' Set DestValueObj to the SetngNameStr's Value.
''' </summary>
''' <param name="SetngNameStr"></param>
''' <param name="DestValueObj"></param>
''' <param name="UserScopedBool"></param>
''' <remarks></remarks>
Public Sub AddGetMySetting( _
ByVal SetngNameStr As String, _
ByRef DestValueObj As Object, _
Optional ByVal UserScopedBool As Boolean = True, _
Optional ByVal RoamingBool As Boolean = False _
)
AddMySetting( _
SetngNameStr:=SetngNameStr, _
DfltValueObj:=DestValueObj, _
UserScopedBool:=UserScopedBool, _
RoamingBool:=RoamingBool _
)
DestValueObj = My.Settings.Item(SetngNameStr)
End Sub
Public Sub LoadFormSettings(ByVal Frm As Form)
Dim FrmSetngBaseName As String = Frm.Name
Dim PrevNumProps As Integer = My.Settings.Properties.Count
AddGetMySetting( _
SetngNameStr:=FrmSetngBaseName & SN_WinState, _
DestValueObj:=Frm.WindowState, _
RoamingBool:=True _
)
AddGetMySetting( _
SetngNameStr:=FrmSetngBaseName & SN_WinLocation, _
DestValueObj:=Frm.Location, _
RoamingBool:=True _
)
AddGetMySetting( _
SetngNameStr:=FrmSetngBaseName & SN_WinSize, _
DestValueObj:=Frm.Size, _
RoamingBool:=True _
)
'If PrevNumProps <> My.Settings.Properties.Count Then
' My.Settings.Save()
'End If
End Sub
''' <summary>
''' Adds (if necessary) and sets a My.Setting Defintion and its Value, respectively, using the specified
''' Setting Name (SetngNameStr), Source Value (SrceValueObj), User Scoped? Flag (UserScopedBool) and
''' Roaming? Flag (RoamingBool).
''' </summary>
''' <param name="SetngNameStr"></param>
''' <param name="SrceValueObj"></param>
''' <param name="UserScopedBool"></param>
''' <param name="RoamingBool"></param>
''' <remarks></remarks>
Public Sub AddSetMySetting( _
ByVal SetngNameStr As String, _
ByVal SrceValueObj As Object, _
Optional ByVal UserScopedBool As Boolean = True, _
Optional ByVal RoamingBool As Boolean = False _
)
AddMySetting( _
SetngNameStr:=SetngNameStr, _
DfltValueObj:=SrceValueObj, _
UserScopedBool:=UserScopedBool, _
RoamingBool:=RoamingBool _
)
My.Settings.Item(SetngNameStr) = SrceValueObj
End Sub
Public Sub SaveFormSettings(ByVal Frm As Form)
Dim FrmSetngBaseName As String = Frm.Name
AddSetMySetting( _
SetngNameStr:=FrmSetngBaseName & SN_WinState, _
SrceValueObj:=Frm.WindowState, _
RoamingBool:=True _ _
)
AddSetMySetting( _
SetngNameStr:=FrmSetngBaseName & SN_WinLocation, _
SrceValueObj:=Frm.Location, _
RoamingBool:=True _ _
)
AddSetMySetting( _
SetngNameStr:=FrmSetngBaseName & SN_WinSize, _
SrceValueObj:=Frm.Size, _
RoamingBool:=True _ _
)
My.Settings.Save()
End Sub