Voraussetzung
-
Die Anwendung TIA Portal Openness ist mit TIA Portal verbunden
Siehe Verbindung zum TIA Portal aufbauen -
Ein Projekt ist geöffnet
Siehe Projekt öffnen
Einleitung
Sie können mit TIA Portal Openness PLC-Meldetextlisten exportieren und importieren. Der Export/Import erfolgt im Format XLSX.
Struktur der Excel-Datei
Die generierte XLSX-Datei besteht aus zwei Tabellenblättern – einem für die Textlisten und einem für die Einträge. Die erstellte XLSX-Datei empfängt bei dem Vorgang eine benutzerdefinierte Eigenschaft namens FileContent mit dem Wert "Alarm text lists". Wenn diese Eigenschaft fehlt oder ungültig ist (keinen oder einen abweichenden Wert enthält), wird der Import abgelehnt.
Die Daten der beiden Arbeitsblätter sind miteinander verknüpft. Dabei verweist das übergeordnete TextListEntry.Parent auf TextList.Name
Modell des Engineering-Objekts
Die Definition des Engineering-Objektmodells für den neu eingeführten Typ PlcAlarmTextListProvider. Der Zugriff darauf erfolgt über die Engineering-Objekte PlcUnit und PlcSoftware.
Exportieren
Für den Exportvorgang stehen die zwei API-Methoden zur Verfügung. Wenn alle Textlisten einer PLC-/Software Unit in allen aktivierten Projektsprachen exportiert werden sollen, ist der einzige benötigte Parameter "path".
Er definiert den Speicherort, an dem sich die XLSX-Ergebnisdatei nach erfolgreichem Export befinden soll.
|
|
|---|
|
FileInfo fileInfo = new FileInfo(Path.Combine(Environment.CurrentDirectory, $"{xlsxName}.xlsx")); PlcAlarmTextListProvider textListProvider = GetTextListProvider(unitName); textListProvider.ExportToXlsx(fileInfo); |
Wenn nicht alle Textlisten einer PLC/Software Unit exportiert werden müssen oder wenn die Sprachen – für die der Textlistenexport vorgesehen ist – gefiltert werden sollen, ist in der API eine andere Methode verfügbar.
Damit werden die zu exportierenden Textlisten über die Liste der Textlistennamen angegeben und die Sprachen, für die der Export erfolgen soll, über die Liste der Sprachen angegeben.
Fehlerbehandlung:
-
Wenn die angegebene Sprache nicht als Projektsprache aktiviert ist, wird die UserException ausgelöst. Beispielsweise kann "Erforderliche Sprache 'Konkani (Indien)' nicht exportiert werden, weil es sich dabei nicht um eine im Projekt verwendete Sprache handelt. Die gültigen Sprachen sind dagegen 'Deutsch (Deutschland)', 'Englisch (USA)'"
-
Wenn keine Anwendertextliste vorhanden ist, wird eine UserException (TextListNotFoundException) mit folgender Meldung ausgelöst: "Zu folgendem Element ist keine Textliste vorhanden: <PLCName>."
-
Wenn ein bestimmter Textlistenname nicht vorhanden ist oder wenn er vorhanden ist, aber keine Anwendertextliste dazu existiert, wird eine UserException ausgelöst. Beispiele: "Textliste Benutzer_1 wird unter PLC_1 nicht gefunden."
"Textliste SYSTEM_SDiag_CmpCpuName kann nicht exportiert werden, da es sich nicht um eine Anwendertextliste handelt."
Beispiel für die Verwendung der Aktion ExportToXlsx:
|
|
|---|
|
private void ExportPlcOrUnit( string stationName, string plcName, string xlsxName, string[] textListNames, string[] cultureCodes, string unitName = null) { LanguageSettings languageSettings = Project.LanguageSettings; LanguageComposition supportedLanguages = languageSettings.Languages; IEnumerable<Language> cultureInfos = null; if (cultureCodes != null) { cultureInfos = cultureCodes.Select(i => supportedLanguages.Find(CultureInfo.GetCultureInfo(i))); } FileInfo fileInfo = new FileInfo(Path.Combine(Environment.CurrentDirectory, $"{xlsxName}.xlsx")); PlcAlarmTextListProvider textListProvider = GetTextListProvider(stationName, plcName, unitName); TextListXlsxResult result = null; string exceptionMessage = string.Empty; ExceptionMessageData? userExceptionMessageData = null; try { result = textListProvider.ExportToXlsx(fileInfo, textListNames, cultureInfos); } catch (EngineeringTargetInvocationException e) { exceptionMessage = e.ToString(); userExceptionMessageData = e.DetailMessageData.FirstOrDefault(); } } private PlcAlarmTextListProvider GetTextListProvider(string stationName, string plcName, string unitName = null) { DeviceComposition devices = Project.Devices; Device device = devices.Where(station => station.Name == stationName).FirstOrDefault(); if (device == null) { throw new InvalidOperationException($"The requested '{stationName}' station is not found"); } PlcSoftware plcTarget = (PlcSoftware)FindSoftwareTarget(device, plcName); if (plcTarget == null) { throw new InvalidOperationException($"The requested '{plcName}' PLC SW is not found") } if (unitName != null) { PlcUnitProvider unitProvider = plcTarget.GetService<PlcUnitProvider>(); PlcUnit unit = unitProvider.UnitGroup.Units.Where(unit => unit.Name == unitName).FirstOrDefault(); if (unit == null) { throw new InvalidOperationException($"The requested '{unitName}' unit is not found"); } return unit.GetService<PlcAlarmTextListProvider>(); } return plcTarget.GetService<PlcAlarmTextListProvider>(); } |
Importieren
Der folgende Importvorgang ist unter der Klasse PLCAlarmTextListProvider verfügbar. Der Parameter ImportFromXlsx akzeptiert fileInfo path als erforderlichen Parameter, der den Speicherort einer importierten XLSX-Datei festlegt.
Mit dem Parameter importOptions als zweitem Parameter in ImportFromXlsx kann festgelegt werden, ob beim Import vorhandene Textlisten überschrieben werden sollen.
Wenn der Parameter importOptions auf ImportOptions.None gesetzt ist und beim Import eine bereits vorhandene Textliste aktualisiert werden soll, wird eine UserException ausgelöst.
Wurde der Parameter importOptions auf ImportOptions.Override gesetzt, werden die bereits vorhandenen Textlisten beim Import aktualisiert.
Vorhandene Textlisten werden über ihren Namen identifiziert. Neue Daten (Textliste, Eintrag) werden an vorhandene Daten angehängt. Vorhandene Textlisten werden nur gelöscht, wenn es in der Importdatei entsprechende Daten gibt.
Enthält also die Excel-Datei Textlisteneinträge für eine bereits vorhandene Textliste, werden die vorhandenen Einträge gelöscht und die in der Excel-Datei enthaltenen Einträge werden in das TIA-Projekt für die
betreffende Textliste importiert (dabei werden keine Textlisteneinträge zusammengeführt).
Beispiel für die Verwendung der Aktion ImportFromXlsx:
|
|
|---|
|
private TextListXlsxResultState ImportPlcOrUnit( string xlsxName, string unitName = null) { FileInfo fileInfo = new FileInfo(Path.Combine(Environment.CurrentDirectory, $"{xlsxName}.xlsx")); PlcAlarmTextListProvider textListProvider = GetTextListProvider(unitName); // Definition of GetTextListProvider is at previous Export example. TextListXlsxResult result = null; try { //Import result = textListProvider.ImportFromXlsx(fileInfo, ImportOptions.Override); } catch (EngineeringTargetInvocationException e) { //Critical error case: No data imported. E.g. Missing or invalid xlsx file. System.Diagnostics.Debug.WriteLine(e.Message); // Write the place and the reason of the error. System.Diagnostics.Debug.WriteLine(e.DetailMessageData.First().Text); // Write the the reason of the error only. return TextListXlsxResultState.Error; } if (result.State == TextListXlsxResultState.OK) { System.Diagnostics.Debug.WriteLine("All Xlsx imported successfully."); } else if (result.State == TextListXlsxResultState.Warning) { //Some text list has not imported. E.g. Duplicated row, invalid range, invalid project language. System.Diagnostics.Debug.WriteLine($"Xlsx imported partially. More details at {result.LogFilePath} file."); } return result.State; } |
Wenn die Datei ungültige Einträge enthält, wird die Textliste mit den ungültigen Einträgen nicht importiert. (Beispiele für ungültige Einträge: Überschneidung zwischen Einträgen oder Datentyp abweichend vom Datentyp der Textliste, die die Einträge enthält).
Die Texte werden nur in den Sprachen importiert, die im Projekt aktiv sind. Wenn die Datei mehr Sprachen als das Projekt enthält, wird der Text in den zusätzlichen Sprachen nicht importiert und eine Warnung
wird protokolliert. Wenn das Projekt mehr Sprachen als die Datei umfasst, werden Texte, für die keine entsprechenden Daten in der Datei vorhanden sind, nicht bearbeitet (oder bleiben leer, falls beim Import neue Textlisten oder Textbereiche eingefügt werden).
In ein schreibgeschütztes Projekt können keine Daten importiert werden. Falls ein Benutzer versucht, Daten in ein schreibgeschütztes Projekt zu importieren, müsste eine UserException ausgelöst werden.
Ein Import ist ein komplexer Vorgang, bei dem verschiedenartige Fehler auftreten können. Wenn der Fehler kein kritischer Fehler ist, wird der Importvorgang beendet und die Methode gibt ein Objekt TextListXlsxResult zurück, das
den Pfad zur Protokolldatei enthält (die wiederum die während des Imports erzeugten Meldungen enthält) und das den Status TextListXlsxResultState.Warning hat.
Wenn der Fehler ein kritischer Fehler ist, wird eine UserException ausgelöst, die Details zum Fehler enthält. Handelt es sich um einen fatalen Fehler, wird eine NonRecoverableException ausgelöst.
|
|
|---|
|
<?xml version="1.0" standalone="no"?> <?xml-stylesheet type='text/xsl' href='MassDataHandlerLogFile.xsl'?> <LogFile titleName="PLCAlarmTextLists_InvalidLanguage.xlsx__2019.06.07_13.46.45.070__Import_Log.xml" projectName="D:\TIA\dev\WM5_WinCC_HW_Work\binaries\Debug\x64\Tests\Siemens.Simatic.AlarmServices.Integration.Test.Openness\TextListXlsxFiles\PLCAlarmTextLists_InvalidLanguage.xlsx" typeText="Type" messageText="Message" timeText="Time"> <LogEntry type="Warning" dateTime="3:46:45 PM"> <Message>The language ID in column 'Comment [abcd-EF]' is missing or is invalid (sheet 'TextList'). The texts in this language are not imported.</Message> </LogEntry> <LogEntry type="Warning" dateTime="3:46:45 PM"> <Message>The language ID in column 'Text [abcd-EF]' is missing or is invalid (sheet 'TextListEntry'). The texts in this language are not imported. </Message> </LogEntry> <LogEntry type="Information" dateTime="3:46:45 PM"> <Message>Import completed: 2 text lists with 9 entries.</Message> </LogEntry> </LogFile> |
|
Hinweis
|
Ergebnis
Das Objekt TextListXlsxResult enthält Informationen über das Ergebnis des Exports bzw. Imports. Es umfasst ein FileInfo-Attribut namens LogFilePath, das auf die Protokolldatei für den beendeten Vorgang verweist. Als Status
(vom Typ TextListXlsxResultState) wird der Endzustand des Vorgangs angezeigt, der entweder OK, "Warning" oder "Error" lautet. Beim Ergebnis "Error" ist der Vorgang fehlgeschlagen, bei "Warning" war der Vorgang teilweise
erfolgreich.