ArcGIS Help 10.2 - Anpassen des Verhaltens von Skriptwerkzeugen

Die Validierung umfasst alle Schritte, bevor auf die Schaltfläche OK eines Werkzeugs geklickt wird. Wenn Sie benutzerdefinierte Werkzeuge erstellen, können Sie anhand der Validierung anpassen, wie Parameter reagieren und mit Werten und anderen Parametern interagieren. Die Validierung erfolgt mit einem Python-Codeblock, der zum Steuern des Werkzeugverhaltens verwendet wird.

Weitere Informationen zur Validierung finden Sie unter Validierung in Skriptwerkzeugen.

Sie können für das Dialogfeld "Skriptwerkzeug" benutzerdefiniertes Verhalten festlegen, etwa das Aktivieren und Deaktivieren von Parametern, das Bereitstellen von Standardwerten und das Aktualisieren von Zeichenfolgen-Schlüsselwörtern. Um für ein Skriptwerkzeug benutzerdefiniertes Verhalten festzulegen, klicken Sie mit der rechten Maustaste auf das Skriptwerkzeug, wählen Sie dann zuerst die Option Eigenschaften, und klicken Sie anschließend auf die Registerkarte Validierung. Im Fenster "Validierung" können Sie mit Python-Code die Python-Klasse "ToolValidator" implementieren.

Die ToolValidator-Klasse wird zwar mit Python-Code implementiert, für die eigentliche Funktion des Werkzeugs können Sie jedoch jede Skriptsprache verwenden.

ToolValidator ist eine Python-Klasse mit drei Methoden: initializeParameters(self), updateParameters(self) und updateMessages(self). Darüber hinaus enthält diese Klasse die Python-Standardmethode für die Klasseninitialisierung, __init__(self). Zum Anzeigen und Bearbeiten der ToolValidator-Klasse klicken Sie mit der rechten Maustaste auf das Skriptwerkzeug und wählen dann zuerst die Option Eigenschaften und anschließend die Registerkarte Validierung aus. In der folgenden Abbildung sehen Sie die Registerkarte Validierung mit dem Standardcode der ToolValidator-Klasse. Klicken Sie auf die Schaltfläche Bearbeiten, um den Code zu bearbeiten. Klicken Sie anschließend auf OK oder Übernehmen, um die vorgenommenen Änderungen zu übernehmen.

Methode	Beschreibung
__init__	Initialisiert die ToolValidator-Klasse. Importieren Sie alle benötigten Bibliotheken, und initialisieren Sie das Objekt (self).
initializeParameters	Wird beim ersten Öffnen des Werkzeugdialogfeldes bzw. bei der ersten Verwendung des Werkzeugs in der Befehlszeile ein Mal aufgerufen.
updateParameters	Wird bei jeder Parameteränderung im Werkzeugdialogfeld aufgerufen. Im Anschluss an "updateParameters" ruft die Geoverarbeitung ihre eigene interne Prüfroutine auf.
updateMessages	Wird im Anschluss an die interne Prüfroutine aufgerufen. Sie können die von der internen Prüfung erstellten Meldungen überprüfen und ggf. ändern.

Übersicht über ToolValidator-Methoden

Hinweis:

Rufen Sie keine anderen Geoverarbeitungswerkzeuge in ToolValidator auf, und öffnen Sie keine Datasets in ToolValidator, denn die ToolValidator-Klasse wird bei jeder Änderung im Werkzeugdialogfeld seitens des Benutzers ausgeführt. Geoverarbeitungswerkzeuge werden im Skript, aber nicht in der ToolValidator-Klasse verwendet.

Hinweis:

Sie müssen die drei Methoden initializeParameters(self), updateParameters(self) und updateMessages(self)implementieren, da sie die ToolValidator-Klasse zu einer gültigen Python-Klasse machen.

Nachfolgend sind einige Beispiele für ToolValidator-Code aufgeführt. Eine vollständige Beschreibung aller Methoden sowie weitere Beispiele finden Sie unter Programmieren einer ToolValidator-Klasse.

Aktivieren bzw. deaktivieren eines Parameters

Dieses Beispiel stammt aus dem Werkzeug Hot Spot Analysis:

def updateParameters(self):

  # If the option to use a weights file is selected (the user chose
  #  "Get Spatial Weights From File"), enable the parameter for specifying 
  #  the file, otherwise disable it
  #
  if self.params[3].value == "Get Spatial Weights From File":
    self.params[8].enabled = 1
  else:
    self.params[8].enabled = 0

Hinweis zum Code: Wenn Sie boolesche Variablen festlegen, beispielsweise Enabled, können Sie folgende Syntaxmuster verwenden:

self.params[8].enabled = 1
self.params[8].enabled = bool(1)
self.params[8].enabled = True  # Note upper case: "True", not "true"

Alle Zahlen oder Werte, die nicht null sind, werden als "true" angesehen.

Festlegen eines Standardwertes

Dieses Beispiel stammt ebenfalls aus dem Werkzeug Hot Spot Analysis:

def updateParameters(self):
  # Set the default distance threshold to 1/100 of the larger of the width
  #  or height of the extent of the input features.  Do not set if there is no 
  #  input dataset yet, or the user has set a specific distance (Altered is true).
  # 
  if self.params[0].value:
    if not self.params[6].altered:
      extent = arcpy.Describe(self.params[0].value).extent
      if extent.width > extent.height:
        self.params[6].value = extent.width / 100
      else:
        self.params[6].value = extent.height / 100

  return

Aktualisieren eines Filters

Das folgende Beispiel zeigt, wie Sie einen Wertelistefilter mit einer Auswahlliste von Schlüsselwörtern dynamisch aktualisieren. Wenn Benutzer beim zweiten Parameter "OLD_FORMAT" eingeben, enthält der dritte Parameter die Werte "POINT", "LINE" und "POLYGON". Bei Eingabe von "NEW_FORMAT" enthält der dritte Parameter drei weitere Optionen.

class ToolValidator:
  def __init__(self): 
    import arcpy 
    self.params = arcpy.GetParameterInfo()

  def initializeParameters(self):
    return

  def updateParameters(self):
    # Provide default values for "file format type" and 
    #  "feature type in file"
    #
    if not self.params[1].altered:
      self.params[1].value = "OLD_FORMAT"
    if not self.params[2].altered:
      self.params[2].value = "POINT"

    # Update the value list filter of the "feature type in file" parameter 
    #   depending on the type of file (old vs. new format) input
    #
    if self.params[1].value == "OLD_FORMAT":
      self.params[2].filter.list = ["POINT", "LINE", "POLYGON"]
    elif self.params[1].value == "NEW_FORMAT":
      self.params[2].filter.list = ["POINT", "LINE", "POLYGON",
                                    "POINT_WITH_ANNO",
                                    "LINE_WITH_ANNO",
                                    "POLYGON_WITH_ANNO"]

    return

  def updateMessages(self):
    return

Im Folgenden finden Sie ein weiteres Beispiel, bei dem sich der Wertelistefilter im zweiten Parameter an den im ersten Parameter angetroffenen Shape-Typ (eine Feature-Class) anpasst:

def updateParameters(self):
    # Update the value list filter in the second parameter based on the 
    #   shape type in the first parameter
    #
    stringFilter = self.params[1].filter
    fc = self.params[0].value
    if fc:
        shapetype = arcpy.Describe(fc).shapeType.lower()
        if shapetype == "point" or shapetype == "multipoint":
            stringFilter.list = ["RED", "GREEN", "BLUE"]
        elif shapetype == "polygon":
            stringFilter.list = ["WHITE", "GRAY", "BLACK"]
        else:
            stringFilter.list = ["ORANGE", "INDIGO", "VIOLET"]
    else:
        stringFilter.list = ["RED", "GREEN", "BLUE"]

    # If the user hasn't changed the keyword value, set it to the default value
    #  (first value in the value list filter).
    #
    if not self.params[1].altered:
        self.params[1].value = stringFilter.list[0]
        
    return

Anpassen einer Meldung

def updateMessages(self):
  self.params[6].clearMessage()

  # Check to see if the threshold distance contains a value of zero and the user has
  #  specified a fixed distance band.
  #
  if self.params[6].value <= 0:
    if self.params[3].value == "Fixed Distance Band":
      self.params[6].setErrorMessage("Zero or a negative distance is invalid \
                                      when using a fixed distance band. Please \
                                      use a positive value greater than zero." )
    elif self.params[6].value < 0:
      self.params[6].setErrorMessage("A positive distance value is required \
                                      when using a fixed distance band. \
                                      Please specify a distance.")

  return

Aktualisieren der Beschreibung von Ausgabedaten mit dem Schema-Objekt

Neben der Anpassung des Verhaltens des Werkzeugdialogfeldes können Sie mit der ToolValidator-Klasse auch die Beschreibungen der Ausgabedatenvariablen für ModelBuilder aktualisieren. Sie können sich Datenvariablen in ModelBuilder einfach als kurze Beschreibungen von Datasets wie unten dargestellt vorstellen. Datenvariablen enthalten alle Eigenschaften, auf die Sie mit der Funktion Describe in Python zugreifen.

Alle Werkzeuge sollten die Beschreibung ihrer Ausgabedaten für die Verwendung in ModelBuilder aktualisieren. Durch die Aktualisierung der Beschreibung können nachfolgende Prozesse in ModelBuilder erkennen, ob Datenänderungen ausstehen, bevor ein Prozess ausgeführt wird. Die beiden folgenden Beispiele zeigen, wie nachfolgende Prozesse ausstehende Änderungen erkennen.

Das erste unten dargestellte Beispiel zeigt ein Modell mit den Werkzeugen Feld hinzufügen und Feld berechnen. Bei Feld hinzufügen wird die Ausgabe-Datenvariable Parks (2) so aktualisiert, dass sie das neue Feld "TrackingID" enthält. Da die Ausgabe aktualisiert wird, ist im Dialogfeld Feld berechnen der Eintrag "TrackingID" in der Liste der Feldnamen enthalten.

Das zweite Beispiel (keine Abbildung) ist ein Modell, bei dem die Ausgabe des Werkzeugs Ausschneiden als Eingabe für das Werkzeug Polygon in Raster fungiert. Da das Werkzeug Ausschneiden die Eingabe-Features wie mit einer Ausstechtechnik erstellt, verfügt die Ausgabe-Feature-Class über die gleichen Eigenschaften wie die Eingabe-Feature-Class, mit einer wichtigen Ausnahme, nämlich der geographischen Ausdehnung. Die geographische Ausdehnung der Ausgabe-Feature-Class ist der geometrische Schnittpunkt der Eingabe-Feature- und der Clip-Feature-Ausdehnung. Das Werkzeug Polygon in Raster bestimmt anhand der neuen geographischen Ausdehnung die standardmäßige Zellengröße.

In der ToolValidator-Klasse können Sie mit einem Schema-Objekt Regeln für den Aufbau der Ausgabebeschreibung festlegen. Sie haben beispielsweise die Möglichkeit, folgende Regeln zu definieren:

Erstellen einer Kopie der Beschreibung für das Eingabe-Dataset und Hinzufügen eines neuen Feldes zur Felderliste (wie bei Feld hinzufügen) bzw. Hinzufügen einer Liste fester Felder (wie bei XY-Koordinaten hinzufügen)
Festlegen der Liste mit den Ausgabefeldern auf alle Felder in einer Dataset-Sammlung und ggf. Hinzufügen von Feldern mit den Feature-IDs aus der Dataset-Sammlung (wie bei Vereinigen und Überschneiden)
Festlegen der Ausdehnung auf die Ausdehnung eines Datasets in einem anderen Parameter oder auf die Vereinigung bzw. Überschneidung (wie bei Ausschneiden) von Datasets in einer Liste mit Parametern.
Festlegen eines bestimmten Geometrietyps (Punkt, Linie, Polygon) bzw. Festlegen des Typs auf den Typ eines Datasets in einem anderen Parameter bzw. auf den minimalen oder maximalen Typ in einer Liste mit Parametern. Die Definition des minimalen und maximalen Geometrietyps lautet Punkte = 0, Polylinien = 1, Polygone = 2. Dies bedeutet, dass der minimale Geometrietyp in der Gruppe "{Punkt, Polylinie, Polygon}" "Punkt" und der maximale Geometrietyp "Polygon" ist.

Ausgabeparameter verfügen über ein Schema

Das Schema-Objekt wird von der Geoverarbeitung erstellt. Jeder Ausgabeparameter des Typs Feature-Class, Tabelle, Raster oder Workspace verfügt über ein Schema-Objekt. Nur die Ausgabe-Datentypen "Feature-Class", "Tabelle", "Raster" und "Workspace" verfügen über ein Schema. Sie greifen über das Parameter-Objekt auf das Schema zu und legen Regeln für die Ausgabebeschreibung fest. Im Anschluss an updateParameters überprüft die interne Prüfroutine die festgelegten Regeln und aktualisiert die Ausgabebeschreibung.

Festlegen von Abhängigkeiten

Wenn Sie beispielsweise die Regel "Die Dataset-Felder in Parameter 3 kopieren und dann ein Feld hinzufügen" erstellen, müssen Sie für das Schema-Objekt angeben, aus welchem Parameter kopiert werden soll (Parameter 3). Sie erreichen dies, indem Sie dem Parameter-Objekt Abhängigkeiten hinzufügen. Sie können auch mehrere Abhängigkeiten hinzufügen.

def initializeParameters(self):
  # Set the dependencies for the output and its schema properties
  #
  self.params[2].parameterDependencies = [0, 1]

Für parameterDependencies ist eine Python-Liste erforderlich.

Die folgenden Beispiele zeigen, wie Sie Abhängigkeiten festlegen und verwenden.

Beispiele für das Festlegen von Abhängigkeiten: "Ausschneiden" und "Feld hinzufügen"

Zur Erinnerung: Das Werkzeug Ausschneiden erstellt eine Kopie der Eingabe-Feature-Definition und legt dann die Ausdehnung auf den Schnittpunkt zwischen Eingabe-Features und Clip-Features fest. Das folgende Beispiel zeigt, wie diese Regel in ToolValidator implementiert wird. (Da es sich bei Ausschneiden um ein integriertes Werkzeug und kein Skript handelt, wird keine Python-ToolValidator-Klasse verwendet. Integrierte Werkzeuge führen die Validierung mit internen Routinen durch, die im Wesentlichen der ToolValidator-Klasse entsprechen. Würde das Werkzeug jedoch die Python-Klasse "ToolValidator" verwenden, sähe diese wie folgt aus.)

def initializeParameters(self):
  # Set the dependencies for the output and its schema properties
  #
  self.params[2].parameterDependencies = [0, 1]

  # Feature type, geometry type, and fields all come from the first 
  #  dependent (parameter 0), the input features
  #
  self.params[2].schema.featureTypeRule = "FirstDependency"
  self.params[2].schema.geometryTypeRule = "FirstDependency"
  self.params[2].schema.fieldsRule = "FirstDependency"

  # The extent of the output is the intersection of the input features and 
  #  the clip features (parameter 1)
  #
  self.params[2].schema.extentRule = "Intersection"

  return

def updateParameters(self):
  return

Das Werkzeug Feld hinzufügen kopiert die Definition eines Eingabeparameters und fügt das benutzerdefinierte Feld hinzu. Wenn Sie den folgenden Link aufrufen, erfahren Sie, wie die Funktion Feld hinzufügen in ToolValidator implementiert wird.

Beispiel für die Verwendung von "AdditionalFields"

Festlegen des Schemas in "initializeParameters" im Vergleich zu "updateParameters"

Beachten Sie, dass im obigen Beispiel mit dem Werkzeug Ausschneiden das Schema-Objekt in initializeParameters geändert wird und dass updateParameters lediglich zurückgibt. Feld hinzufügen dagegen muss das Schema-Objekt in updateParameters ändern, da dieser Funktion die Definition des hinzuzufügenden Feldes erst dann zur Verfügung steht, wenn ein Benutzer Informationen bereitstellt (und updateParameters aufgerufen wird).

Sie können sich diese beiden Fälle als statisch im Vergleich zu dynamisch vorstellen. Ausschneiden ist lediglich auf die Datasets in den abhängigen Parametern angewiesen (statisch), während Feld hinzufügen andere (unabhängige) Parameter wie etwa den Feldnamen und den Feldtyp überprüfen muss (dynamisch).

Dieses statische und dynamische Verhalten wird an der Art und Weise deutlich, wie eine ToolValidator-Klasse aufgerufen wird:

Beim ersten Öffnen des Werkzeugdialogfeldes wird initializeParameters aufgerufen. Sie legen die statischen Regeln für die Ausgabebeschreibung fest. Zu diesem Zeitpunkt wird keine Ausgabebeschreibung erstellt, da der Benutzer keine Werte für die Parameter bereitgestellt hat.
Sobald ein Benutzer mit dem Werkzeugdialogfeld interagiert, wird updateParameters aufgerufen.
updateParameters kann das Schema ändern, um dynamischem Verhalten Rechnung zu tragen, das nicht anhand der Parameterabhängigkeiten bestimmt werden kann, wie etwa das Hinzufügen eines neuen Feldes mit Feld hinzufügen.
Im Anschluss an updateParameters werden die internen Prüfroutinen aufgerufen und die Beschreibung der Ausgabedaten wird anhand der im Schema-Objekt enthaltenen Regeln aktualisiert.
Anschließend wird updateMessages aufgerufen. Sie können die von der internen Prüfung ausgegebenen Warnungen und Fehlermeldungen überprüfen und ggf. ändern bzw. weitere Warnungen und Fehlermeldungen hinzufügen.

Name des Ausgabe-Datasets: Klonen einer abgeleiteten Ausgabe im Vergleich zur erforderlichen Ausgabe

Wenn Sie für die Eigenschaft Schema.Clone den Wert "true" festlegen, weisen Sie die Geoverarbeitung an, eine exakte Kopie (einen Klon) der Beschreibung im ersten abhängigen Parameter in der Liste mit den Parameterabhängigkeiten zu erstellen. Normalerweise wird die Kloneigenschaft in initializeParameters und nicht in updateParameters auf "true" festgelegt, da sie nur einmal festgelegt werden muss.

Falls "ParameterType" für den Ausgabeparameter auf "Derived" gesetzt wird, wird eine exakte Kopie angefertigt. Dieses Verhalten findet man beim Werkzeug Feld hinzufügen.

Falls "ParameterType" auf "Required" gesetzt wird, wird ebenfalls eine exakte Kopie angefertigt, der Katalogpfad zum Dataset wird jedoch geändert. Da die meisten Werkzeuge neue Daten erstellen, ist dies das gängigste Verhalten.

Weitere Informationen

Unter Programmieren einer ToolValidator-Klasse finden Sie genaue Informationen zum Parameter-, Schema- und Filterobjekt sowie Codebeispiele.

Alle skriptbasierten Systemwerkzeuge, etwa das Werkzeug Mehrfachring-Puffer verfügen über ToolValidator-Code, den Sie überprüfen und studieren können. Viele Werkzeuge in der Toolbox Spatial Statistics Tools sind Skriptwerkzeuge mit einer ToolValidator-Implementierung, die Sie untersuchen können.

Fehler bei der ToolValidator-Implementierung – Syntax-, Laufzeit- oder logische Fehler – können nicht immer vermieden werden. Unter Debuggen einer ToolValidator-Klasse erfahren Sie, wie die Geoverarbeitung Fehler abfängt und meldet. Darüber hinaus erhalten Sie Tipps für das Debugging, also die Fehlerbeseitigung.

Anpassen des Verhaltens von Skriptwerkzeugen