The Technical Adventures of Adam Weigert

I <3 PowerShell

2011-03-28T15:58:00Z

This blog author has moved to iheartpowershell.com

dynamic? I'll never use that ... or then again, maybe it could ...

2010-05-27T01:04:00Z

So, I don't know about you, but I was highly skeptical of the dynamic keywork when it was announced. I thought to myself, oh great, just another move towards VB compliance.

Well after seeing it being used in things like DynamicXml (which I use for this example) I then was working with a MVC controller and wanted to move some things like operation timeout of an action to a configuration file. Thinking big picture, it'd be really nice to have configuration for all my controllers like that. Ugh, I don't want to have to create all those ConfigurationElement objects...

So, I started thinking self, use what you know and do something cool ...

Well after a bit of zoning out, self came up with use a dynamic object duh! I was thinking of a config like this ...

<controllers>
  <add type="MyApp.Web.Areas.ComputerManagement.Controllers.MyController, MyApp.Web">
    <detail timeout="00:00:30" />
  </add>
</controllers>

So, I ended up with a couple configuration classes like this ...

blic abstract class DynamicConfigurationElement : ConfigurationElement
{
    protected DynamicConfigurationElement()
    {
        this.DynamicObject = new DynamicConfiguration();
    }

    public DynamicConfiguration DynamicObject
    {
        get;
        private set;
    }

    protected override bool OnDeserializeUnrecognizedAttribute(string name, string value)
    {
        this.DynamicObject.Add(name, value);
        return true;
    }

    protected override bool OnDeserializeUnrecognizedElement(string elementName, XmlReader reader)
    {
        this.DynamicObject.Add(elementName, new DynamicXml((XElement)XElement.ReadFrom(reader)));
        return true;
    }
}

public class ControllerConfigurationElement : DynamicConfigurationElement
{
    [ConfigurationProperty("type", Options = ConfigurationPropertyOptions.IsRequired | ConfigurationPropertyOptions.IsKey)]
    public string TypeName
    {
        get { return (string)this["type"]; }
    }

    public Type Type
    {
        get { return Type.GetType(this.TypeName, true); }
    }
}

public class ControllerConfigurationElementCollection : ConfigurationElementCollection
{
    protected override ConfigurationElement CreateNewElement()
    {
        return new ControllerConfigurationElement();
    }

    protected override object GetElementKey(ConfigurationElement element)
    {
        return ((ControllerConfigurationElement)element).Type;
    }
}

And then had to create the meat of the DynamicConfiguration class which looks like this ...

public class DynamicConfiguration : DynamicObject
{
    private Dictionary<string, object> properties = new Dictionary<string, object>(StringComparer.CurrentCultureIgnoreCase);

    internal void Add<T>(string name, T value)
    {
        this.properties.Add(name, value);
    }

    public override bool TryGetMember(GetMemberBinder binder, out object result)
    {
        var propertyName = binder.Name;

        result = null;

        if (this.properties.ContainsKey(propertyName))
        {
            result = this.properties[propertyName];
        }

        return true;
    }
}

So all being said, I made a base controller class like a good little MVC-itizen ...

public abstract class BaseController : Controller
{
    protected BaseController()
        : base()
    {
        var configuration = ManagementConfigurationSection.GetInstance();
            
        var controllerConfiguration = configuration.Controllers.ForType(this.GetType());

        if (controllerConfiguration != null)
        {
            this.Configuration = controllerConfiguration.DynamicObject;
        }
    }

    public dynamic Configuration
    {
        get;
        private set;
    }
}

And used it like this ...

public class MyController : BaseController
{
    static readonly string DefaultDetailTimeout = TimeSpan.MaxValue.ToString();

    public MyController()
    {
        this.DetailTimeout = TimeSpan.Parse(this.Configuration.Detail.Timeout ?? DefaultDetailTimeout);
    }

    public TimeSpan DetailTimeout
    {
        get;
        private set;
    }
}

And there I have an actual use for the dynamic keyword ... never thoguht I'd see the day when I first heard of it as I don't do much COM work ... oh dont' forget this little helper extension methods to find the controller configuration by the controller type.

public static ControllerConfigurationElement ForType<T>(this ControllerConfigurationElementCollection collection)
{
    Contract.Requires(collection != null);
    return ForType(collection, typeof(T));
}

public static ControllerConfigurationElement ForType(this ControllerConfigurationElementCollection collection, Type type)
{
    Contract.Requires(collection != null);
    Contract.Requires(type != null);
    return collection.Cast<ControllerConfigurationElement>().Where(element => element.Type == type).SingleOrDefault();
}

Sure, it isn't perfect and I'm sure I can tweak it over time, but I thought it was a pretty cool way to take advantage of the dynamic keyword functionality. Just remember, it only validates you did it right at runtime, which isn't that bad ... is it? And yes, I did make it case-insensitive so my code didn't have to look like my XML objects, tweak it to your liking if you dare to use this creation.

The WaitForAll Roadshow

2010-05-26T12:41:00Z

OK, so I took for granted some imaginative uses of WaitForAll but lacking that, here is how I am using. First, I have a nice little class called Parallel that allows me to spin together a list of tasks (actions) and then use WaitForAll, so here it is, WaitForAll's 15 minutes of fame ...

First Parallel that allows me to spin together several Action delegates to execute, well in parallel.

public static class Parallel
{
    public static ParallelQuery<Action> Task(Action action)
    {
        return new Action[] { action }.AsParallel();
    }

    public static ParallelQuery<Action<T>> Task<T>(Action<T> action)
    {
        return new Action<T>[] { action }.AsParallel();
    }

    public static ParallelQuery<Action> Task(this ParallelQuery<Action> actions, Action action)
    {
        var list = new List<Action>(actions);
        list.Add(action);
        return list.AsParallel();
    }

    public static ParallelQuery<Action<T>> Task<T>(this ParallelQuery<Action<T>> actions, Action<T> action)
    {
        var list = new List<Action<T>>(actions);
        list.Add(action);
        return list.AsParallel();
    }
}

Next, this is an example usage from an app I'm working on that just is rendering some basic computer information via WMI and performance counters. The WMI calls can be expensive given the distance and link speed of some of the computers it will be trying to communicate with. This is the actual MVC action from my controller to return the data for an individual computer.

public PartialViewResult Detail(string computerName)
{
    var computer = this.Computers.Get(computerName);
    var perf = Factory.GetInstance<IPerformanceCounterProvider>();

    var detail = new ComputerDetailViewModel()
        {
            Computer = computer
        };

    try
    {
        var work = Parallel
            .Task(delegate 
            {
                // Win32_ComputerSystem
                var key = computer.Name + "_Win32_ComputerSystem";
                var system = this.Cache.Get<Win32_ComputerSystem>(key);

                if (system == null)
                {
                    using (var impersonation = computer.ImpersonateElevatedIdentity())
                    {
                        system = computer.GetWmiContext().GetInstances<Win32_ComputerSystem>().Single();
                    }

                    this.Cache.Set(key, system);
                }

                detail.TotalMemory = system.TotalPhysicalMemory;
                detail.Manufacturer = system.Manufacturer;
                detail.Model = system.Model;
                detail.NumberOfProcessors = system.NumberOfProcessors;
            })
            .Task(delegate 
            {
                // Win32_OperatingSystem
                var key = computer.Name + "_Win32_OperatingSystem";
                var os = this.Cache.Get<Win32_OperatingSystem>(key);

                if (os == null)
                {
                    using (var impersonation = computer.ImpersonateElevatedIdentity())
                    {
                        os = computer.GetWmiContext().GetInstances<Win32_OperatingSystem>().Single();
                    }

                    this.Cache.Set(key, os);
                }

                detail.OperatingSystem = os.Caption;
                detail.OSVersion = os.Version;
            })
            // Performance Counters
            .Task(delegate 
            {
                using (var impersonation = computer.ImpersonateElevatedIdentity())
                {
                    detail.AvailableBytes = perf.GetSample(computer, "Memory", "Available Bytes");
                }
            })
            .Task(delegate 
            {
                using (var impersonation = computer.ImpersonateElevatedIdentity())
                {
                    detail.TotalProcessorUtilization = perf.GetValue(computer, "Processor", "% Processor Time", "_Total");
                }
            }).WithExecutionMode(ParallelExecutionMode.ForceParallelism);

        if (!work.WaitForAll(TimeSpan.FromSeconds(15), task => task()))
        {
            return PartialView("Timeout");
        }
    }
    catch (Exception ex)
    {
        this.LogException(ex);
        return PartialView("Error.ascx");
    }

    return PartialView(detail);
}

Reinventing the Paged IEnumerable, Weigert Style!

2010-05-25T20:16:00Z

I am pretty sure someone else has done this, I've seen variations as PagedList<T>, but this is my style of a paged IEnumerable collection. I just store a reference to the collection and generate the paged data when the enumerator is needed, so you could technically add to a list that I'm referencing and the properties and results would be adjusted accordingly.

I don't mind reinventing the wheel when I can add some of my own personal flare ...

// Extension method for easy use
public static PagedEnumerable AsPaged(this IEnumerable collection, int currentPage = 1, int pageSize = 0)
{
    Contract.Requires(collection != null);
    Contract.Assume(currentPage >= 1);
    Contract.Assume(pageSize >= 0);

    return new PagedEnumerable(collection, currentPage, pageSize);
}

public class PagedEnumerable : IEnumerable
{
    public PagedEnumerable(IEnumerable collection, int currentPage = 1, int pageSize = 0)
    {
        Contract.Requires(collection != null);
        Contract.Assume(currentPage >= 1);
        Contract.Assume(pageSize >= 0);

        this.collection = collection;
        this.PageSize = pageSize;
        this.CurrentPage = currentPage;
    }

    IEnumerable collection;

    int currentPage;
    public int CurrentPage
    {
        get 
        {
            if (this.currentPage > this.TotalPages)
            {
                return this.TotalPages;
            }

            return this.currentPage; 
        }
        set
        {
            if (value < 1)
            {
                this.currentPage = 1;
            }
            else if (value > this.TotalPages)
            {
                this.currentPage = this.TotalPages;
            }
            else
            {
                this.currentPage = value;
            }
        }
    }

    int pageSize;
    public int PageSize
    {
        get 
        {
            if (this.pageSize == 0)
            {
                return this.collection.Count();
            }

            return this.pageSize;
        }
        set
        {
            this.pageSize = (value < 0) ? 0 : value;
        }
    }

    public int TotalPages
    {
        get
        {
            return (int)Math.Ceiling(this.collection.Count() / (double)this.PageSize);
        }
    }

    public IEnumerator GetEnumerator()
    {
        var pageSize = this.PageSize;
        var currentPage = this.CurrentPage;
        var startCount = (currentPage - 1) * pageSize;
            
        return this.collection.Skip(startCount).Take(pageSize).GetEnumerator();
    }

    IEnumerator IEnumerable.GetEnumerator()
    {
        return this.GetEnumerator();
    }
}

PLINQ Adventure Land - WaitForAll

2010-05-23T17:28:00Z

PLINQ is awesome for getting a lot of work done fast, but one thing I haven't figured out yet is how to start work with PLINQ but only let it execute for a maximum amount of time and react if it is taking too long. So, as I must admit I am still learning PLINQ, I created this extension in that ignorance. It behaves similar to ForAll<> but takes a timeout and returns false if the threads don't complete in the specified amount of time. Hope this helps someone else take PLINQ further, it definitely has helped for me ...

public static bool WaitForAll<T>(this ParallelQuery<T> query, TimeSpan timeout, Action<T> action)
{
    Contract.Requires(query != null);
    Contract.Requires(action != null);

    var exception = (Exception)null;
    var cts = new CancellationTokenSource();
            
    var forAllWithCancellation = new Action(delegate
    {
        try
        {
            query.WithCancellation(cts.Token).ForAll(action);
        }
        catch (OperationCanceledException)
        {
            // NOOP
        }
        catch (AggregateException ex)
        {
            exception = ex;
        }
    });
            
    var mrs = new ManualResetEvent(false);
    var callback = new AsyncCallback(delegate { mrs.Set(); });
    var result = forAllWithCancellation.BeginInvoke(callback, null);
            
    if (mrs.WaitOne(timeout))
    {
        forAllWithCancellation.EndInvoke(result);

        if (exception != null)
        {
            throw exception;
        }

        return true;
    }
    else
    {
        cts.Cancel();
        return false;
    }
}

Overriding Inheritance for IIS 6.0 Virtual Directories

2010-02-09T14:46:00Z

If you have an IIS site that has a mixture of ASP.NET 1.1 and 2.0 virtual directories below it, changing the root site ASP.NET settings could affect the virtual directory ASP.NET settings as well since IIS inherits except for explicit overrides. This little PowerShell script will take each setting and persist it to the virtual directory so you are able to freely change the root site settings without affecting the applications below it.

Please remember to backup your IIS settings before you do this, just incase it has adverse affects on your IIS server.

function Persist-IIsSettings ( $obj ) {
    Write-Host $obj.Path
    
    $obj.Properties.GetEnumerator() |% {
        $propertyName = $_.PropertyName
        $value        = $obj.Get($propertyName)
        
        if ( -not ($value -is [System.__ComObject]) ) {
            $obj.Put($propertyName, $value)
        }
    }
    
    $obj.SetInfo()

    $obj.Children |% { Persist-IIsSettings $_ }
}

Persist-IIsSettings ([ADSI]"IIS://localhost/W3SVC/1/ROOT")

ASP.NET PowerShell Data Source Control

2010-02-04T04:16:00Z

Extending on the small proof-of-concept I mentioned yesterday I created this simple data source control that lets you bind a Repeater or DataGrid to it like an ObjectDataSource control but it executes a PowerShell script to retrieve the results.

<asp:PowerShellDataSource ID="EmployeesDataSource" runat="server">
    [PSObject]"" | Add-Member NoteProperty "Title" "Software Engineer" -passThru | Add-Member NoteProperty "Name" "Mike Wolford" -passThru
    [PSObject]"" | Add-Member NoteProperty "Title" "Software Evangelist" -passThru | Add-Member NoteProperty "Name" "Scott Root" -passThru
</asp:PowerShellDataSource>



<asp:Repeater runat="server" DataSourceID="EmployeesDataSource">
    <ItemTemplate>
        <h4><%# DataBinder.Eval(Container.DataItem, "Title") %>: <%# DataBinder.Eval(Container.DataItem, "Name") %></h4>
    </ItemTemplate>
</asp:Repeater>

If this is something that interests you, take a look over at http://aspower.codeplex.com/

ASP.NET PowerShell Runspace Control

2010-02-03T04:16:00Z

This is just a little concept project I am working on so I can run PowerShell scripts within my ASP.NET applications. As I am a server administrator, I love PowerShell + WMI, and bringing this power into ASP.NET my automation capabilities are being greatly simplified. I'll build on this solution as I play around with actually implementing this as a primary source of automation from support a Windows Server environment.

I am aware of other projects/products that allow you to do similar things, I just needed something simple, and I don't want to code an entire page in PowerShell, just specific tasks.

http://aspower.codeplex.com/

LINQ: Expressive Html Tag Building

2009-01-02T03:31:00Z

I hate building HTML tags in code, but it needs to be done. I just wanted to make it a little cleaner. So I came up with this method that utilizes LINQ expressions to generate the attributes for the tag. This is really only clean with simple tags, but I use it with my other tag building methods to keep them clean as well. I've seen others look for something like this and thought it'd be helpful posting it here. I haven't deeply tested this code but it shows the general concept and I'm sure it needs cleaned up a little. The following is an example calling the Tag method:

   1:  Tag( "a", "The Technical Adventures of Adam Weigert", href => "http://weblogs.asp.net/adweigert/" );

   2:  Tag( "div", "LINQ Expressions Rock", style => "font-size: 250%; font-weight: bold;", id => "title" );

This is the actual method, I love how simple the LINQ expression makes building the attributes.

   1:  public string Tag( string tagName, string innerHtml, params Expression<Func<string, string>>[] attributes )

   2:  {

   3:      XElement tag = new XElement( XName.Get( tagName, string.Empty ) );

4:

   5:      if ( attributes != null )

   6:      {

   7:          foreach ( var attribute in attributes )

   8:          {

   9:              string attributeName = attribute.Parameters[ 0 ].Name;

  10:              string attributeValue = attribute.Compile()(string.Empty);

11:

  12:              tag.SetAttributeValue( XName.Get( attributeName, string.Empty ), attributeValue );

  13:          }

  14:      }

15:

  16:      if ( !string.IsNullOrEmpty( innerHtml ) )

  17:      {

  18:          tag.Add( XElement.Parse( "<xml>" + innerHtml + "</xml>" ).Nodes() );

  19:      }

20:

  21:      return tag.ToString();

  22:  }

Update: Used XElement instead, and better innerHtml handling. Thanks to everyone that helped improve this method.

PowerShell: Install-Gac (GACUTIL for PowerShell)

2008-10-31T19:16:00Z

So, I don't know about anyone else, but it is a pain to use GACUTIL on systems without the .NET SDK. So, I found out there is a .NET API for GACUTIL, so now I just wrapped it in PowerShell to make it easier to use. :)

   1:  BEGIN {

   2:      $ErrorActionPreference = "Stop"

3:

   4:      if ( $null -eq ([AppDomain]::CurrentDomain.GetAssemblies() |? { $_.FullName -eq "System.EnterpriseServices, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" }) ) {

   5:          [System.Reflection.Assembly]::Load("System.EnterpriseServices, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") | Out-Null

   6:      }

7:

   8:      $publish = New-Object System.EnterpriseServices.Internal.Publish

   9:  }

  10:  PROCESS {

  11:      $assembly = $null

12:

  13:      if ( $_ -is [string] ) {

  14:          $assembly = $_

  15:      } elseif ( $_ -is [System.IO.FileInfo] ) {

  16:          $assembly = $_.FullName

  17:      } else {

  18:          throw ("The object type '{0}' is not supported." -f $_.GetType().FullName)

  19:      }

20:

  21:      if ( -not (Test-Path $assembly -type Leaf) ) {

  22:          throw "The assembly '$assembly' does not exist."

  23:      }

24:

  25:      if ( [System.Reflection.Assembly]::LoadFile( $assembly ).GetName().GetPublicKey().Length -eq 0 ) {

  26:          throw "The assembly '$assembly' must be strongly signed."

  27:      }

28:

  29:      Write-Output "Installing: $assembly"

30:

  31:      $publish.GacInstall( $assembly )

  32:  }

CodePlex: The Weigert Repository

2008-10-02T20:44:00Z

I've been looking for a place to keep / manage all the snippets I develop or find and decided to use CodePlex for this. Feel free to use whatever you find useful.

http://www.codeplex.com/Weigert

PowerShell: Oh Happy Days Are Here (Dynamically Compiling C# Code for Strongly Typed Objects within PowerShell)

2008-09-30T00:15:00Z

Ever wanted to build native .NET objects to use while in a PowerShell script? Well I certainly have, and finally took the time to figure out how easy it is to actually do! Enjoy!

function Compile-Code {
    param (
        [string[]] $code       = $(throw "The parameter -code is required.")
      , [string[]] $references = @()
      , [switch]   $asString   = $false
      , [switch]   $showOutput = $false
      , [switch]   $csharp     = $true
      , [switch]   $vb         = $false
    )
    
    $options    = New-Object "System.Collections.Generic.Dictionary``2[System.String,System.String]";
    $options.Add( "CompilerVersion", "v3.5")
    
    if ( $vb ) {
        $provider = New-Object Microsoft.VisualBasic.VBCodeProvider $options
    } else {
        $provider = New-Object Microsoft.CSharp.CSharpCodeProvider $options
    }
    
    $parameters = New-Object System.CodeDom.Compiler.CompilerParameters
    
    @( "mscorlib.dll", "System.dll", "System.Core.dll", "System.Xml.dll", ([System.Reflection.Assembly]::GetAssembly( [PSObject] ).Location) ) + $references | Sort -unique |% { $parameters.ReferencedAssemblies.Add( $_ ) } | Out-Null
    
    $parameters.GenerateExecutable = $false
    $parameters.GenerateInMemory   = !$asString
    $parameters.CompilerOptions    = "/optimize"
    
    if ( $asString ) {
        $parameters.OutputAssembly = [System.IO.Path]::GetTempFileName()
    }
    
    $results = $provider.CompileAssemblyFromSource( $parameters, $code )
    
    if ( $results.Errors.Count -gt 0 ) {
        if ( $output ) {
            $results.Output |% { Write-Output $_ }
        } else {
            $results.Errors |% { Write-Error $_.ToString() }
        }
    } else {
        if ( $asString ) {
            $content = [System.IO.File]::ReadAllBytes( $parameters.OutputAssembly )
            $content = [Convert]::ToBase64String( $content )
            
            [System.IO.File]::Delete( $parameters.OutputAssembly );
            
            return $content
        } else {
            return $results.CompiledAssembly
        }        
    }
}

Example usage:

Compile-Code -csharp -code @"
    using System;
    
    public class Foo {
        public Foo ( string message ) {
            Message = message;
        }
    
        public string Message { get; private set; }
        
        public void Bar() {
            Console.WriteLine( "Foo.Bar: {0}", Message );
        }
    }
"@

$foo = New-Object Foo "hello world"
$foo.Bar()

Update: Added ability to compile C# or VB.NEt code and also to return the bytes for the compiled assembly for loading at a later time.

PowerShell: Keeping Secrets for Batch Scripts

2008-08-27T16:01:00Z

As a system administrator, I write a lot of utility scripts, and I love using PowerShell. However, I cannot always use the local scheduler with a service account to run a script, sometimes I have to provide a username and password to an application or service. I hate storing them in plaintext, and while I don't fully like storing the encrypted text, key, and IV in the script, it is one step better than the plaintext solution. While the ultimate solution would be to have it stored as part of the user profile for the job, this is an issue when I don't have direct access to the production system to be able to run as the service account and I just need an encrypted file / text to later decrypt and use.

So, I started working with ConvertTo/From-SecureString and hit a little problem. I discovered, via Reflector, that the ConvertTo-SecureString and ConvertFrom-SecureString use an IV that is specific to that instance of the PowerShell runtime. Thus, using it at a later time is no good for me. So, long story short, I cranked up Reflector, took a look at the commands, and created a script version that does exactly what I need.

You will find the script attached.

PowerShell: Adding the Using Statement

2008-08-27T15:56:00Z

So, I happened to come across a need for the using statement from C#. I basically didn't want to use Try...Finally when I am so used to the short-hand using statement. Thank goodness I already have a Try..Catch..Finally statement/function for PowerShell, I can just use that existing framework and make a using statement/function pretty easily.

function Using {
    param (
        [System.IDisposable] $inputObject = $(throw "The parameter -inputObject is required."),
        [ScriptBlock] $scriptBlock = $(throw "The parameter -scriptBlock is required.")
    )
    
    Try {
        &$scriptBlock
    } -Finally {
        if ($inputObject -ne $null) {
            if ($inputObject.psbase -eq $null) {
                $inputObject.Dispose()
            } else {
                $inputObject.psbase.Dispose()
            }
        }
    }
}

# Short example ... 
Using ($user = $sr.GetDirectoryEntry()) { 
  $user.displayName = $displayName 
  $user.SetInfo() 
}

Update: Take note on variable scope, variables in the using statement will not be available outside of it, this can make it tricky, but it should be easy enough to work with.

PowerShell: Threading Enhancements FTW!

2008-04-30T13:11:00Z

To build on the threading library I mentioned here, I've added some functionality to make it easier to communicate with the seperate thread. Still, keep in mind that PowerShell will only allow one pipeline to be executing in a runspace at any given time. So, these new functions can only be used while the thread is inactive. But, they provide power into setting up the thread to be run and communicating with the original runspace.

The new functions are as follows:

Get-ThreadVariable - Accesses available variables from within the thread.
Set-ThreadVariable - Sets a variable for use within the thread.
Invoke-ThreadExpression - Allows synchronous execution of a script block within the thread.

I also updated the Join-Thread function to include an optional -timeout parameter so that you could return control back if the thread didn't complete in the desired time. I also updated the Running property to IsRunning and changed it so that it will only return true while the asynchronous invoke command is executing.

With this new example you can do even more now, as shown here.

$thread = New-Thread
Invoke-ThreadExpression $thread { function foo($bar) { echo "$bar!" } }
Set-ThreadVariable $thread "name" "PowerShell Rocks"
Start-Thread -thread $thread { $value = foo $name } | Out-Null
Join-Thread $thread
Get-ThreadVariable $thread "value"

This should return "PowerShell Rocks!" when Get-ThreadVariable is called. I've already used this script to multi-thread our Exchange backup from a single script. It is working quite nicely (nice as in have cut our 8 hour backup down to 4 hours) and I can already imagine several other wonderful places it will be used.