Scoprirete che su Office non si può solo contare ma anche sviluppare
1
Smart Documents
Luca Regnicoli
MCSD.NET MCSE+I MCDBA MCT
[email protected]
2
Agenda
• Cos’è una soluzione SmartDocument
• Requisiti di una soluzione SmartDocument
• Architettura di SmartDocument
– Assembly e ISmartDocument
– Manifest
– Schema
• Security
• XML & Office System 2003
• Deploy
• Tips & Tricks
3
Cosa diamo per scontato
• Conoscenza di base del .NET Framework
– Interface, Ereditarietà
– Code Access Security
4
Smart Document Basics – Parte I
5
Che cavolo è una soluzione SmartDocument?
• Soluzione che fornisce informazioni
contestuali ed azioni all’interno del task
pane
• Scenari di utilizzo
– Compilazione di un’offerta commerciale
– Generazione di un documento contrattuale
– Gestione di un budget finanziario
6
Requisiti di una soluzione
• PC Client
– Office System 2003 Professional
• oppure versioni stand-alone di Word o Excel
2003
– Se utilizziamo .NET
• .NET Framework 1.1
7
Requisiti di una soluzione
• PC Sviluppo
– Office System 2003 Professional
– Visual Studio .NET 2003
• Oppure un ambiente di sviluppo COM
– Microsoft Office SmartDocument SDK
• Non è fondamentale, ma è un utile
“contenitore” di sample, tool e documentazione
8
Architettura Smart Document
Office document
Manifest file
Schema file
DLL Assembly
Altri assembly
XML expansion pack
9
DLL / Assembly
• Deve contenere una classe che implementi
l’interfaccia COM ISmartDocument
• Può essere scritto con qualsiasi linguaggio
che sia in grado di implementare un
interfaccia COM
– Visual Basic 6.0
– Visual C++ 6.0
– Delphi
– .NET (Interop)
10
Interfaccia ISmartDocument
• Proprietà
–SmartDocXmlTypeCount
–SmartDocXmlTypeCaption
–SmartDocXmlTypeName
–ControlCount
–ControlID
–ControlNameFromID
–ControlCaptionFromID
–ControlTypeFromID
• Metodi
–SmartDocInitialize
–Populate<ControlType>
–On<ControlType>Change
–ImageClick
–InvokeControl
11
ISmartDocument
• Non posso invocare direttamente i metodi o le
proprietà
• Devo “attendere” che il runtime passi il controllo ai
nostri metodi/proprietà
– ControlCount
– PopulateListOrComboContent
• Non pilotiamo direttamente i controlli
– NO textBox1.Text = “Luca”
– NO string s = comboBox1.SelectedItem.Text
• Non possiamo gestire esplicitamente eventi sui
controlli
– NO private void button1_Click (object o, EventArgs e)
12
Terminologia
• Tipi Xml
– Contenitori di controlli
– Definiti nei metodi SmartDocXmlType*
• Controlli Smart Document
– Controlli UI definiti all’interno di tipi XML
– Definiti nei metodi Control*
– Devono avere ID unico all’interno dell’intero
task pane
13
Creare Tipi Xml
• SmartDocXmlCount
–1on
• SmartDocXmlName
– NomeSchema#nomeElementoDelloSchema
– Per creare un task pane persistent
• #actionPertainsToEntireSchema
• SmartDocXmlCaption
– “Esempio di SmartDocument”
14
Creare controlli Smart Document
• ControlCount
–2
• ControlID
– Come associare l’ID al controllo
– Utilizzare ControlIndex passatoci dal runtime
• ControlTypeFromID
– Il controllo con ID = 1 è una textbox
– Il controllo con ID = 2 è un pulsante
15
Controlli Smart Document
•
•
•
•
•
•
•
•
•
•
•
Images
Hyperlinks
Check boxes
List boxes
Combo boxes
Radio buttons
Text boxes
Labels
Separators
ActiveX controls
Document fragments
16
Gestire click
• InvokeControl
switch (ControlID)
{
case 1:
MessageBox.Show (“Pulsante cliccato”); break;
case 2:
....
}
17
Struttura del file Manifest
<manifest xmlns=
"http://schemas.microsoft.com/office
/xmlexpansionpacks/2003">
descrizione del manifest
<solution>
descrizione della solution
</solution>
</manifest>
18
Manifest - Elementi file
<solution>
. . .
<file>
<type>solutionActionHandler</type>
<filePath>bin\Codice.dll</filePath>
<CLSNAME>Libreria.ClasseAzione</CLSNAME>
<managed/>
</file>
</solution>
19
Manifest - Elementi file
<solution>
. . .
<file>
<type>schema</type>
<version>1</version>
<filePath>bin\Schema.xsd</filePath>
</file>
</solution>
20
Schema
<xs:schema xmlns=“Devleap.SmartDocuments.Demo"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
...
<xs:element name="cliente">
<xs:element name="nome" type="xs:string"/>
<xs:element name="cognome" type="xs:string"/>
<xs:element name="email" type="xs:string" />
</xs:element>
...
</xs:schema>
21
Security
• XML expansion pack security
– Manifest può essere caricato solo se è stato
firmato con un certificato digitale
• XMLSign.exe [SDK]
• DisableXMLExpansionPackSecurity.reg
– Solo sulle macchine di sviluppo!
• Se utilizziamo .NET
– Office si “fida” di mscoree.dll
– Ma non si “fida” del nostro assembly
– L’assembly deve avere permission di FullTrust
22
Collegare Manifest al documento
• In Word 2003
– Menu “Tools” - “Templates and Add-ins”
• In Excel 2003
– Menu “Data“ - ”XML” - “XML Expansion Packs”
23
Sviluppo .NET
• Utilizzare i Primary Interop Assembly per
Office
• Microsoft.Office.Interop.SmartTag.dll
– ISmartDocument
• Microsoft.Office.Interop.Excel
• Microsoft.Office.Interop.Word
• Per aggiornamenti di Service Pack di
Microsoft
24
Primary Interop Assembly
• Come vedere se sono installati
– Global Assembly Cache
25
Primary Interop Assembly
• Come installare
Microsoft.Office.Interop.SmartTag.dll
26
Primary Interop Assembly
• Come installare
Microsoft.Office.Interop.Word.dll
27
Primary Interop Assembly
• Come vedere se li stiamo referenziando
correttamente da Visual Studio .NET
28
Ricapitolando... Step By Step
•
•
•
•
•
•
•
•
•
Aggiungere la reference COM a “Microsoft Smart Tag 2.0 Type Lib“
Implementare l’interfaccia ISmartDocument
Definire il namespace di base
Definire il tipo XML del doc #actionPertainsToEntireSchema”
Implementare le proprietà dell’interfaccia ISmartDocument
– Caption dei controlli
– Numero di controlli
– Id dei controlli
– Tipo di controlli
– Nome dei controlli
– Controllare le azioni dei controlli quali button
– Impostare la caption del task pane
– Numero di tipi xml del task pane
– Nome dei tipi xml del task pane
Creare lo schema xml
Creare il manifest
Configurare la Code Access Security
– L’assembly deve avere diritto di FullTrust
Aggiungere l’xml expansion pack al documento
29
Demo … finalmente del codice 
30
Smart Document Basics – Parte II
31
Formattazione di controlli
• Nei metodi Populate* utilizzare la variabile
di tipo ISmartDocProperties per “scrivere” il
valore delle proprietà di formattazione
Props.Write (“Align”, “Center”);
• Per l’elenco delle proprietà disponibile
vedere la documentazione
– Reference -> ISmartDocProperties ->
Interfaces -> ISmartDocProperties Interface
32
Textbox1.Text... Dov’è?
private string valoreTextbox = String.Empty;
public void OnTextboxContentChange(…, string Value)
{
valoreTextbox = Value;
}
public void InvokeControl( …)
{
MessageBox.Show (“Il valore è: “ + valoreTextbox );
}
33
ComboBox
private string valoreSelezionatoCombo = String.Empty;
public void PopulateListOrComboContent(…, ref Array List, ref int Count, ref int
InitialSelected)
{
string[] elementi = new string[3] {“Pulp Fiction”, “Matrix”, “Giovannona coscialunga”};
List = elementi;
Count = 3;
}
//InitialSelected = -1; //InitialSelected = 2
public void OnListOrComboSelectChange(…, int Selected, string Value)
{
valoreSelezionatoCombo = Value;
}
public void InvokeControl( …)
{
}
MessageBox.Show (“Il selezionato è: “ + valoreSelezionatoCombo );
34
Integrazione con Word
private _Document objWord;
public void SmartDocInitialize(.. , object Document, ...)
{
objWord = (_Document)Document;
}
public void InvokeControl(...)
{
objWord.Application.Selection.TypeText ("Ho scritto sul
documento");
}
35
Integrazione con Excel
private _Workbook objExcel;
public void SmartDocInitialize(.. , object Document, ...)
{
objExcel = (_Workbook)Document;
}
public void InvokeControl(...)
{
_Worksheet objSheet = (_Worksheet)objExcel.ActiveSheet;
Range objRange = objSheet.get_Range("A1", Type.Missing);
objRange.set_Value(Type.Missing, "Ho scritto nella cella");
}
36
RefreshPane
• Metodo RefreshPane permette di eseguire
un refresh dell’intero task pane
– Che fantasia eh!
• Tutti i metodi e proprietà verranno
richiamati
• Alcuni utilizzi
– Per rendere visibili/invisibili dei controlli
– Per caricare immagini diverse
• Scenario ComboBox, Immagine legata alla
combo
37
XML e Office 2003
• Utilizzare un modello di programmazione
xml-oriented al posto di vba-oriented
– Il documento espone nodi xml
– Posso individuarli, leggerli ed impostarli
• Word 2003
– SelectSingleNode
– SelectNodes
• Excel 2003
– XmlMapQuery
38
Dynamic Task Pane
• Capacità di caricare sezioni del task pane
diverse in funzione della posizione del
cursore sul documento
• Basato sugli elementi dello schema e sul
relativo mapping all’interno documento
39
Dynamic Task Pane - Step 1
• Creare lo schema con diversi elements
<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns="Devleap.SmartDocuments.Demo” >
<xs:element name="demo">
<xs:element name="cliente">
<xs:element name="nome" type="xs:string" />
<xs:element name="cognome" type="xs:string" />
</xs:element>
</xs:element>
</xs:schema>
40
Dynamic Task Pane - Step 2
• Mappare gli elementi dello schema sul
documento
41
Dynamic Task Pane - Step 3
• Modificare il codice aggiungendo i tipi xml
– SchemaNamespace#ElementName
– Devleap.SmartDocuments.Demo#cliente
• Modificare il codice aggiungendo la
discriminante dei tipi xml
– ControlCount
switch (XMLTypeName)
case DOC_MAIN
return 2
case DOC_CLIENTE
return 3
42
Smart Document “tips and tricks”
43
Windows Forms
• Windows Forms e Task Pane ??
• Certo sono classi!
– Basta aggiungere una Forms al progetto
• Supporto del designer di Visual Studio .NET
– Instanziare la classe e lanciare il metodo Show
44
Word e Excel
• Word, aggiungendo l’xml expansion pack
– Legge il manifest e recupera le informazioni
legate all’assembly e allo schema
• Excel, aggiungendo l’xml expansion pack
– Legge il manifest e recupera le informazioni
legate all’assembly
– Dobbiamo andare nel menu XML Source per
aggiungere lo schema
• Altrimenti il task pane verrà caricato senza
errori ma risulterà vuoto!
45
Excel
• Elementi di uno schema, di default, per
Excel sono associabili ad UNA SOLA cella
• Soluzione
– maxOccurs=“unbounded”
• XmlDataQuery vs XmlMapQuery
• “Invalid format or old type library”
– Regional settings della macchina sono in una
lingua diversa dall’installazione di Office
• Regional settings in ITA e Office 2003 in ENG
46
Interface
• Word
– _Document o Document
• Funzionalità analoghe ma solo con Document è
possibile intercettare gli eventi del documento
(BeforeDocumentClose ecc.)
• Excel
– _Workbook o Workbook
• Funzionalità analoghe ma solo con Workbook è
possibile intercettare gli eventi del documento
(AfterDocumentSave ecc.)
47
ActiveX
• Creare il controllo con C_TYPE_ACTIVEX
– E fin qui...
• Nel metodo PopulateActiveXProps impostare
– Width ed Height
• Il default è 0 per entrambe!
• Nel ControlCaptionFromId impostare
– Il GUID nella caption del controllo!!!!
• Vi SCONSIGLIO di utilizzarli
– Kg , Kg e kg di bug
48
Debugging da VS.NET
• Nota! Prima dobbiamo “attaccare”
correttamente il manifest
49
Tabelle di Word
• Associando un elemento dello schema ad
una cella di una tabella di Word
• Quando si creerà una nuova riga, l’elemento
verrà ricopiato da Word automaticamente
• Si utilizza il modello vba-oriented
– Per creare la nuova riga
• Si utilizza il modello xml-oriented
– Per leggere la collezione di XMLNodes
contenuta nella tabella
– XMLNodes nodi = SelectNodes(“.../Prezzo”,
...);
50
Deploy Smart Documents
51
Certificato
• Va bene qualsiasi certificato di code-signing
rilasciato da certification authority riconosciute
• La più utilizzata è Verisign
– Microsoft Authenticode Digital ID
• Firma del manifest
– Installa il certificato (.cer) sulla macchina di sviluppo
– Si estrae la chiave privata del certificato
• pvkimprt.exe (sito microsoft.com)
• Se errore di password errata riprovare su Windows
2000
– Si installa la chiave privata
– Lanciare XMLSign.exe e firmare il manifest con il
certificato appena installato
52
caspol.exe
• Tool da riga di comando per modificare la
Code Access Security di .NET
caspol.exe -pp off -ag 1.1 -url
"file://C:/InstallDir/*" FullTrust -n
PolicyDevleap
53
InstallManifest
• Excel
Excel.Application objExcel = new Excel.ApplicationClass();
string pathDocumento = @"c:\installDir\demo.xls";
string pathManifest = @"c:\installDir\manifest.xml";
string pathSchema = @"c:\installDir\schema.xsd";
objWorks = objExcel.Workbooks;
objWork = objWorks.Open(pathDocumento,…);
objWork.XmlNamespaces.InstallManifest(pathManifest …);
objWork.XmlMaps.Add(pathSchema ….);
54
Legame Documento - Manifest
• L’associazione fra il documento ed il manifest viene
mantenuta all’interno delle Custom Property del
documento stesso
– SolutionID e SolutionURL
• Possiamo automatizzare da codice questo processo
Object objProp ;
objProp = objWork.CustomDocumentProperties;
Type typeDocCustomProps = objProp.GetType();
object[] objArgsSolutionId = {"Solution ID", … , "DemoCS.Codebehind"};
typeDocCustomProps.InvokeMember("Add", … , objProp, objArgsSolutionId
);
object[] objArgsSolutionUrl = {"Solution URL", …, pathManifest};
typeDocCustomProps.InvokeMember("Add", … , objProp,
objArgsSolutionUrl );
55
Cartella dei Template
• Copiando un .dot o .xlt nella cartella
predefinita di Office 2003
– Verrà aggiunto ai template disponibili
• New Office Document
• Word o Excel
– New Document -> Templates -> On my computer
• Se si crea una sotto-cartella rispetto alla
directory dei template
– Verrà aggiunto un nuovo tab alla dialog box dei
template disponibili
56
Primary Interop Assembly
• I componenti per .NET se sono installati dopo il
framework hanno l’icona “1” ovvero “Installed on
first use”
– Al primo utilizzo dell’applicazione smartdoc gli verrà
chiesto il cd di setup all’utente
– Oppure silent se ha scelto di mantenere i file di
installazione
• Altrimenti hanno la “X” ovvero “Not Installed”
• E’ sufficiente ri-lanciare (anche in automatico) il
setup di Office System 2003 alla fine del nostro setup
– L’utente dovrà solo fare “Next”
– A questo punto il FW .NET sarà già installato e i
componenti avranno l’icona su “Installed on first use”
57
Step setup - 1
• Installare il .net framework 1.1
• Copiare nella cartella d’installazione il
manifest (firmato con XMLSign.exe), lo
schema e l’assembly
• Copiare nella cartella dei template di office
(o dove vogliamo) il .xlt/.xls o il .dot/.doc
• Lanciare un .exe che associ il manifest al .xlt
e al .dot
58
Step setup - 2
• Lanciare un programma o batch che
modifichi la sicurezza .net, per questo
abbiamo 3 scelte:
– 1) Lanciare un volgarissimo .bat con
caspol.exe
– 2) Lanciare un vbs che grazie agli oggetti
WScript.Shell lanci caspol.exe
– 3) Lanciare un .exe .net che grazie alle classi
del fw cambi i parametri di sicurezza
• Lanciare il setup di Office 2003
– Primary Interop Assembly
59
Scoprirete che su Office non si può solo contare ma anche sviluppare
60