Il namespace My è una novità di Visual Basic 2005: è stato introdotto per fornire un accesso facilitato a classi del framework utili usate molto spesso, diminuendo così il codice necessario e di conseguenza in tempo impiegato a scriverlo. My contiene oggetti singleton aggiornati durante la creazione dell'applicazione nell'ambiente di sviluppo: ad esempio My.Settings viene popolato con le risorse e le impostazioni aggiunte dall'utente, oppure i membri di My.Forms sono aggiunti ogniqualvolta viene aggiunto un form all'applicazione e costituiscono una scorciatoia per richiamarli senza definirne altre istanze. Ecco una panoramica dei membri di My:

• My.Application : espone informazioni sull'applicazione corrente, da dove sia stata lanciata, quale utente la stia utilizzando e con quali permessi e le informazioni assembly quali versione e cultura
• My.Computer : permette un'interazione rapida e veloce con le periferiche del computer quali mouse e tastiera, con il filesystem, con la memoria, con i formati audio e video e permette di gestire le porte seriali e la stampante
• My.Forms : espone una proprietà per ogni form definito, corrispondente alla sua istanza di default
• My.Resources : contiene oggetti che fanno da wrapper a ciascuna risorse utilizzata nel progetto e referenziata esplicitamente
• My.Settings : ogni proprietà corrisponde ad un'impostazione definita nei Settings del progetto. Un oggetto può essere di qualsiasi tipo supportato e può avere scopo differente a seconda che venga usato dall'utente o dal programma
• My.User : restituisce informazioni sull'utente che sya usando il computer
• My.WebServices : permette di usare servizi web e richiamare metodi web senza dovere scrivere lo stesso codice più volte

My.Application

Ecco una lista dei membri più significativi di questo oggetto:

• ApplicationContext : restituisce il contesto applicativo in cui viene eseguito il programma, tramite cui si può ottenere il Main Form
• CommandLineArgs : restituisce una lista in sola lettura a tipizzazione forte di stringhe contenente tutti gli argomenti passati da console al programma. Ond'evitare confusione, per chi provenisse da altri linguaggi, il primo argomento non è il nome del programma stesso ma proprio il primo argomento che viene dopo la dichiarazione dell'applicazione
• Culture : restituisce un oggetto CultureInfo che permette di avere informazioni sulla cultura corrente, in particolare il modo in cui vengono formattati valori e date
• Deployment : restituisce un oggetto ApplicationDeployment che permette di scaricare e aggiornare il programma scaricando i nuovi files da internet. L'uso di questo oggetto verrà trattato in un altro momento, benchè nel momento in cui scrivo, un capitolo al riguardo non sia ancora stato inserito nell'indice della guida
• Info : restituisce un oggetto AssemblyInfo che consente di visualizzare le informazioni sul programma, quali titolo, versione, autore, società, descrizione ecc... Queste impostazioni possono essere fornite al compilatore tramite Designer o tramite codice, ma anche questo punto verrà trattato in seguito
• Log : restituisce un oggetto Log del namespace VisualBasic.Logging, i cui metodi permettono di interagire con i file di log, scrivendo messaggi o report di errori riscontrati a run-time
• OpenForms : se il progetto corrente è una Windows Application, ottiene una collezione di tutti i form aperti
• SaveMySettingsOnExit : se il progetto corrente è una Windows Application, determina qualora tutti i campi della classe My.Settings debbano essere automaticamente salvati prima dell'uscita dal programma
• DoEvents : se il progetto corrente è una Windows Application, processa tutti i messaggi windows in coda. Questo permette che gli eventi siano generati e opportunamente gestiti anche durante lo svolgimento di una procedura particolarmente lunga (come quella di ricerca dei file), oppure che la grafica del form venga correttamente aggiornata, impendendo all'applicazione di assumere un aspetto che verrebbe altrimenti interpretato dall'utente come "bloccato". Sebbene sia molto comodo usare DoEvents in casi del genere, i principi Microsoft suggeriscono invece di utilizzare un controllo BackgroundWorker oppure un thread separato creato manualmente
• GetEnvironmentVariable(S) : restituisce il valore della variabile d'ambiente di nome S. Le variabili d'ambiente sono create, usate e gestite dal sistema operativo e contengono informazioni sulle directory, sui file e sui dettagli tecnici dell'hardware e del software. È possibile ottenere in questo modo, ma anche attraverso la classe System.Environment. Non è sicuro modificare alcune di esse, come ad esempio, la cartella di Windows
• Run(C()) : avvia una nuova istanza di questa applicazione passandole gli argomenti definiti nell'array di stringhe C()

Fra le altre cose, questa classe espone anche degli eventi interessanti: Startup e Shutdown vengono lanciati rispettivamente quando l'applicazione viene aperta o chiusa, ma possono facilmente essere sostituiti dai più semplici FormLoad e FormClosing; interessanti sono invece gli eventi StartupNextInstance, lanciato quando viene avviata un'altra istanza dell'applicazione, UnhandledException, generato ogniqualvolta si riscontra un errore non gestito (e quindi utilissimo per non far apparire la famosa messagebox di errore critico) e NetworkAvaiabilityChanged, che riporta un cambiamento nello stato di usabilità della rete (ossia quando ci si connette o disconnette). Gestire correttamente tali eventi non può che portare benefici alla solidità e all'efficienza del programma.

My.Computer

Ad eccezione di Name, che restituisce il nome del computer, tutte le altre proprietà esposte sono oggetti figli i quali a loro volta mettono a disposizione altre funzionalità: in questo namespace vengono riassunti i metodi più utili sul piano dell'audio, del filesystem, del registro di sistema e del recupero informazioni. Ecco una lista di quasi tutte le proprietà (Ports è stata tralasciata poichè raramente usata, mentre Registry non verrà analizzato, per ovvi motivi):

• Audio

• Play(S, M) : esegue un suono memorizzato in un file Audio Wave (*.wav), definito dal percorso S. È possibile specificare anche, nell'overload, le modalità con cui avviene la riproduzione. Esse sono espresse da un enumeratore a tre valori: Background (musica di sottofondo), BackgroundLoop (la musica viene ripetuta all'infinito, fino a quando non la si ferma manualmente), WaitUntilComplete (aspetta che tutto il file sia riprodotto prima di passare all'istruzione successiva). Ad ogni modo, per la costruzione di un Media Player è assai meglio ricorrere all'aiuto delle librerie DirectX.AudioVideoPlayback
• PlaySystemSound(S) : esegue un suono di default di Windows, definito dall'enumeratore S di tipo System.Media.SystemSound. I valori riportati sono quasi gli stessi dell'enumeratore che definisce le icone della MessageBox: infatti i suoni in questione non sono altro che quelli riprodotti all'apparire di una MessageBox
• Stop : interrompe l'esecuzione di un suono in background

Clipboard (gli appunti)

• Clear : pulisce la clipboard, annullando qualsiasi suo contenuto
• Contains... : le funzioni che iniziano per "Contains" determinano quale tipo di dato contengano gli appunti, se immagini, suoni, files, testo o altro
• Get... : le funzioni che iniziano con "Get" restituiscono il contenuto della clipboard secondo i vari formati
• Set... : allo stesso modo, le funzioni Set impostano il contenuto della clipboard secondo i vari formati

Clock

• LocalTime : restituisce la data e l'ora corrente memorizzate sul computer
• TickCound : restituisce il numero di tick passati dall'accesione del computer. Un tick corrisponde a un milionesimo di secondo, ma questa proprietà, stranamente, restituisce il risultato in millisecondi

FileSystem

• CopyDirectory(S, D, O) : nel suo primo overload, questa procedura copia la directory indicata da S nella directory D; se D non esiste viene creata; se esiste e O (Overwrite) = True, viene sovrascritta
• CopyDirectory(S, D, Show, Cancel) : nel suo secondo overload, copia la directory da S a D; Show è un valore che indica se visualizzare la finestra di copia predefinita di windows, mentre Cancel specifica se è possibile annullare l'operazione tramite tale finestra
• CopyFile(S, D, ...) : copia un file da S a D. Presenta overload uguali a quelli sopra descritti
• CreateDirectory(D) : crea una nuova directory secondo il percorso D fornito
• CurrentDirectory : la directory corrente
• DeleteDirectory(D, F) : elimina una cartella D, specificando tramite F, se si debba generare un'eccezione qualora la cartella non sia vuota
• DeleteDirectory(D, Show, Recycle, Cancel) : elimina la cartella D, eventualmente visualizzando la finestra di dialogo di windows; è possibile specificare se eliminare completamente la cartella o se mandarla nel cestino con Recycle, mentre Cancel indica se sia o meno concessa all'utente la possibilità di annullare l'operazione
• DeleteFile(F, ...) : elimina il file F. Presenta overload uguali a quelli sopra descritti
• DirectoryExists(P) / FileExists(P) : determinano se il file o la cartella P esistano o meno
• Drives : restituisce una collezione in sola lettura a tipizzazione forte di DriveInfo contenente informazioni sui vari drives disponibili
• FindInFiles(P, S, Case, Recurse) : restituisce una collezione in sola lettura a tipizzazione forte di String contenente i nomi di tutti i files trovati. P è la cartella in cui cercare, S è la parola da cercare nel file, Case indica se la ricerca è case sensitive oppure no, mentre Recurse indica se analizzare anche le sottodirectory
• GetDriveInfo(P) / GetDirectoryInfo(P) / GetFileInfo(P) : restituiscono informazioni sul percorso specificato
• GetDirectories(P, R) / GetFiles(P, R) : restituiscono rispettivamente le cartelle e i files presenti nella directory P, eventualmente agendo ricorsivamente se R = True
• GetName(P) : restituisce il nome del file o della cartella (la sua ultima parte)
• GetParentPath(P) : restituisce la cartella che si trova a livello superiore rispetto al file o alla directory P
• GetTempFileName : crea un nuovo file nella cartella temporanea del computer, vuoto, e ne restituisce il percorso
• MoveDirectory : esattamente come CopyDirectory, solo che la cartella di partenza viene rimossa
• MoveFile : come sopra
• OpenTextFieldParser(P, W()) : apre un parser di file di testo sul file P. Questo oggetto legge i valori in esso contenuti seguendo le direttive specificate nel ParamArray W. Se si tratta di dati a larghezza fissa, W specifica le larghezza dei dati; se si tratta di dati separati da caratteri speciali, W specifica quei caratteri
• ReadAllBytes / ReadAllText : leggono tutti i bytes o tutto il testo del file specificato e li/lo restituisce/ono
• RenameDirectory(P, N) / RenameFile(P, N) : rinominano il file o la directory P con un nuovo nome N (solo il nome, non tutto il percorso)
• SpecialDirectories : restituisce un oggetto le cui proprietà indicano il percorso delle cartelle speciali, come i documenti, le immagini, la cartella temporanea, i video, eccetera...
• WriteAllText / WriteAllBytes : scrivono tutto il testo o tutti i bytes dati all'interno del file specificato

Info

• AvaiablePhysicalMemory : l'ammontare di memoria fisica libera sul computer, in bytes
• OSFullName : il nome completo del sistema operativo
• OSPlatform : identifica la piattaforma del sistema operativo
• TotalPhysicalMemory : l'ammontare totale di memoria fisica del computer, in bytes

Keyboard

• AltKeyDown, CtrlKeyDown, ShiftKeyDown : restituiscono True se Alt, Ctrl o Shift risultano premuto nell'istante in cui la funzione viene richiamata
• CapsLock, NumLock, ScrollLock : restituiscono True se sono attivi CpasLock, NumLock o ScrollLock
• SendKeys(K, W) : simula la pressione del tasto K sulla finestra attiva, opzionalmente aspettando finchè tale messaggio non venga processato (W = True)

Mouse

• ButtonsSwapped : determina se i pulsanti destro e sinistro risultano scambiati
• WheelExists : determina se il mouse sia dotato di rotellina
• WheelScrollLines : determina di quante linee si debba scorrere quando la rottelina venga ruotata di una tacca

Network

• DownloadFile(S, D) : scarica il file S sul computer, salvandolo come D. È possibile specificare come terzo e quarto parametro un nome utente e una password nel caso il server in questione ne richieda uno. Il quinto parametro, se presente, specifica se visualizzare la finestra di dialogo di default di windows; il sesto indica l'opzionale timeout di connessione. Il settimo specifica se sovrascrivere un file esistente e il settimo se sia possibile annullare l'operazione. Tutti i parametri dopo il secondo sono opzionali e forniti dagli overloads della funzione
• IsAvaiable : determina se il computer sia connesso o meno a una rete
• Ping(IP, Timeout) : esegue un'operazione di Ping sul server IP (Ip può essere un Ip valido o un Dns). Il ping serve per controllare se il server sia attivo: viene inviato un pacchetto di bytes di controllo; se risponde, significa che è online e funzionante, altrimenti ci sono dei problemi. Si può specificare opzionalmente un Timeout di millisecondi trascorso il quale non si prosegua oltre nell'operazione di Ping
• UploadFile : carica il file su un server. I parametri sono gli stessi di DownloadFile

Screen

• AltScreen : restituisce un array di tutti i dislapy del sistema
• BitsPerPixel : il numero di bit associati ad un unico pixel in memoria
• Bounds : restituisce un oggetto Rectangle contenente le dimensioni dello schermo
• DeviceName : il nome del device associato allo schermo
• PrimaryScreen : lo schermo primario
• WorkingArea : l'area di lavoro

My.User

Espone poche proprietà, la più importante delle quali è Name, che restituisce il nome dell'utente attualmente loggato. Ci sono altre funzioni come IsInRole che permettono anche di definire il ruolo dell'utente (ad esempio Amministratore o Proprietario, oppure un diverso stato se appartiene a un dato gruppo di computer).

My.Resources

È un contenitore in grado di immagazzinare qualsiasi file o risorsa: immagini, video, suoni, file di dati, di testo, stringhe e altro ancora. Tutto quello che viene immesso nell'applicazione attraverso questo wrapper è inglobato nell'assembly finale, mentre durante lo sviluppo del software, tali file vengono temporaneamente salvati nella cartella Resources del progetto. È possibile aggiungere una nuova risorsa dalle proprietà del progetto (Nome progetto->Click col destro->Properties), come mostrato in questa immagine:


Tramite il menù in alto a sinistra nella finestra delle risorse si può scegliere quale tipo di dati aggiungere: la lista al centro visualizza risorse per tipo, quindi in una volta saranno visibili solo stringhe, solo immagini, solo suoni, eccetera... Il pulsante a fianco, "Add Resource" permette di aggiungere una risorsa di quel tipo; le altre sottovoci presenti sono delle scorciatoie per risorse usate spesso come stringhe, immagini o file di testo. Una volta aggiunta una risorsa tramite il designer, il compilatore riscrive automaticamente tutto il codice nascosto di My.Resources, rendendo disponibili come proprietà tutti i dati immessi. A seconda del tipo specificato, tale proprietà sarà restituita in maniera differente:

• Stringhe e file di testo vengono restituiti come String
• Le immagini vengono restituite come System.Drawing.Bitmap
• I suoi vengono restituiti come System.IO.UnmanagedMemoryStream
• Le icone vengono restituite come System.Drawing.Icon
• I file di altro tipo vengono restituiti come array di bytes

My.Settings

Per mezzo di questo oggetto è possibile salvare le impostazioni dell'applicazione che devono permanere tra due sessioni distinte. I settaggi vengono salvati can il supporto dell'XML e della serializzazione in una cartella dal nome chilomentrico all'interno della directory dell'utente corrente. Il nome è stabilito usando le informazioni dell'assembly e il suo strong name. All'avvio, tutti i campi vengono automaticamente impostati dal programma, che si preoccupa prima del caricamento del form, di recuperare il file XML e leggerne il contenuto. In questo risiede la comodità di My.Settings, poichè concede al programmatore la libertà di dedicarsi alla scrittura del codice significativo, delegando poi alla macch

ina l'esecuzione di compiti noiosi quali il caricamento delle impostazioni.
Anche in questo caso, si opera su My.Settings attraverso una finestra nella sezione Properties del progetto. La schermata è semplice e intuitiva, e permette di creare non solo valori di tipi semplici come String, Boolean o Double, ma anche tipi complessi, sia value che reference, anche definiti dallo sviluppatore: il requisito minimo è che siano serializzabili (come si vedrà in seguito, di default, tutti gli oggetti sono serializzabili). Un'applicazione diffusa e molto richiesta per la sua semplicità consiste nel poter salvare valori associati a controlli. Ad esempio, si vuole che il font, il testo e il colore di un pulsante vengano conservati tra una sessione e l'altra. In questo caso, ma anche negli altri, il lavoro da fare non risulta affatto lungo o complesso. Per prima cosa bisogna creare tre nuovi valori attraverso l'interfaccia My.Settings dal pannello di controllo delle proprietà di progetto: uno di tipo Font, uno String e uno Color. Ecco:


(Si faccia caso alla finestra delle proprietà nell'angolo a destra: anche da lì, come se fosse un normale controllo, si possono modificare i campi di My.Settings, eventualmente specificando un commento in Description) Lo scope User o Application riguarda la finalità per cui il campo viene creato: in genere le proprietà User sono modificabili, mentre quelle Application sono ReadOnly. Ora che sono stati creati gli opportuni valori, bisogna collegarli alle rispettive proprietà del pulsante (ovviamente dopo aver creato anche il pulsante). Selezionato il pulsante, bisogna espandere, nella finestra delle proprietà, la voce "(Application Settings)". Al suo intero sarà presente soltanto la voce "Text", alla quale si assegnerà il valore ButtonText, tramite la piccola finestra di dialogo che apparirà cliccandoci sopra. Per le altre due proprietà, ForeColor e Font, bisogna cliccare sul pulsantino coi tre puntini di sospensione sull'elemento appena sopra, "(PropertyBinding)": verrà visualizzata una griglia completa di tutte le proprietà, dando quindi la possibilità di collegare ciascuna al corrispettivo valore. Risultato:


Ora, cambiando un valore di My.Settings, cambierà anche l'aspetto del controllo. Le impostazioni vengono caricate automaticamente all'inizio, ma per salvare bisogna o richiamare il metodo My.Settings.Save oppure impostare a True la proprietà My.Application.SaveMySettingsOnExt.
Per quanto riguarda gli altri metodi di questa classe, è necessario annoverare solo Save, Reload e Reset: dei primi due è facilmente intuibile la funzione; il terzo, invece, reimposta al loro valore di default tutti i valori che vengono dichiarati con Persist = True. Inoltre, sono presenti anchq quattro utili eventi: SettingsChanging (generato prima che venga modificata un'impostazione), PropertyChanged (dopo che è stato cambiato il valore di un'impostazione), SettingsLoaded (all'avvio o dopo aver chiamato i metodi Reload o Reset) e SettingsSaving (prima che vengano salvate le impostazioni). Bisogna notare che gli eventi generati prima che avvenga qualcosa possono anche modificare il comportamento dell'azione oppure anche annullarla, sempre ispezionando le possibilità offerte dai membri di e.

My.Forms e My.WebServices

Espongono le istanze di default di tutti i Form o di tutti i Web Service definiti nel progetto: il secondo tipo di oggetto non è trattato in questa guida.